Skip to content
Get packs

Guide · Open source

How to use Plandex: install, run tasks and review changes

Updated · written with AI from the project's own documentation and checked against our catalogue data

Plandex is an open source, terminal-based AI coding agent designed for large projects and multi-step tasks. This guide explains what it does, how to install it, how to connect a model provider, and how to review its changes before they touch your project. By the end you will know whether it fits your workflow and how to start your first task.

Plandexplandex-ai/plandex · ★ 15.9k · MIT

Quick start

  1. 1Check your platform. On Windows, install and open WSL first. Plandex does not run correctly in CMD or PowerShell.
  2. 2Install the CLI. Run the install script from the README with curl and bash on macOS or Linux.
  3. 3Set a provider key. If you use OpenRouter, export OPENROUTER_API_KEY, or connect a Claude Pro or Max subscription when prompted.
  4. 4Open a project. cd into the project directory you want to change, then run plandex to start the REPL.
  5. 5Describe the task. Load relevant files and describe the multi-step change you want, using chat mode first if you are still exploring.
  6. 6Review and apply. Check the cumulative diff in the review sandbox, then approve the changes to apply them to your project.

What Plandex does and who it is for

Plandex plans and carries out coding tasks that span many steps and many files. It keeps AI-generated changes in a cumulative diff review sandbox, separate from your project files, until you approve them. It can also run commands such as builds, linters, tests and scripts, and debug their output.

It is built for developers working in large codebases, people comfortable in a terminal, and developers who want to choose or compare model providers. It is not a point-and-click tool, and it is not a good fit for Windows users outside WSL.

  • Terminal-based, with a REPL mode and a CLI for scripting
  • Keeps changes in a review sandbox until you apply them
  • Can run and debug terminal commands
  • Supports models from multiple providers

Install Plandex on macOS or Linux

On macOS or Linux, install the CLI with the one-line script from the project README. The README also links to additional installation options in the Plandex docs.

Windows is supported only through WSL. Plandex only works correctly in the WSL shell, not in CMD or PowerShell.

  • Windows users: install WSL first, then run the install inside the WSL shell
curl -sL https://plandex.ai/install.sh | bash

Connect a model provider

Plandex works with model providers using your own keys. If you use OpenRouter, set your OpenRouter API key as an environment variable before you run Plandex. Other providers are configured through the Plandex docs.

If you have a Claude Pro or Max subscription, Plandex can use it when calling Anthropic models. You will be asked whether to connect the subscription the first time you run Plandex.

  • OpenRouter: set OPENROUTER_API_KEY
  • Anthropic via Claude Pro or Max: connect when prompted on first run
export OPENROUTER_API_KEY=... # if using OpenRouter.ai

Start your first task in a project

Change into the project directory you want Plandex to work on, then run plandex. This opens the REPL, where you can load files and describe the task. Use chat mode to explore ideas or ask questions about the codebase before moving to implementation.

Plandex loads only the files it needs for each step. Review the changes in the diff sandbox, then apply them when they look right. Git integration can generate commit messages and optionally commit automatically.

  • Use fuzzy auto-complete for commands and file loading
  • Review the cumulative diff before applying
  • Use branches to explore different paths or compare models
  • Control autonomy from full auto to step-by-step review
cd path/to/your/project plandex

Run Plandex with a self-hosted server

Plandex Cloud is winding down and no longer accepts new users, so new users who want the server should use self-hosted local mode. The README says local mode can run with Docker, or on your own server. Docker is only needed for this option.

Follow the local-mode quickstart in the Plandex docs to set it up.

  • Docker is required only for self-hosting the server in local mode
  • You can use your own OpenRouter key or other provider accounts

What people use it for

  • Making a multi-file feature change in a large codebase
  • Asking questions and learning about an unfamiliar project in chat mode
  • Running builds or tests and letting Plandex debug the terminal output
  • Comparing results from different models using branches

Frequently asked questions

Is Plandex free?

The source says Plandex is open source under the MIT licence. It does not state pricing for model usage; you supply your own provider keys, such as OpenRouter, and those providers may charge for usage. Plandex Cloud is winding down and no longer accepts new users.

Does Plandex work on Windows?

Yes, but only through WSL. The README says Plandex only works correctly in the WSL shell and does not work in the Windows CMD prompt or PowerShell.

Do I need Docker to use Plandex?

Not for the CLI install. Docker is a prerequisite only if you want to self-host the server in local mode.

Can I use Plandex with different AI models?

Yes. The README says you can combine models from Anthropic, OpenAI, Google and open source providers, and use OpenRouter or other provider accounts with your own keys.

Is there a graphical interface?

No. Plandex is terminal-based, so it is not suited to people who want a point-and-click interface.

Can I use Plandex Cloud now?

The README says Plandex Cloud is winding down and no longer accepts new users. New users should look at self-hosted local mode instead.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Plandex suits developers comfortable in a terminal who work in large codebases and want an agent to handle multi-file changes with a review step. It is a poor choice for people who need a graphical interface, Windows users without WSL, or anyone expecting Plandex Cloud to accept new sign-ups.

Install options & downloads