Churn through your backlog, work with unfamiliar technologies, get unstuck, and spend less time on the boring stuff.
Plandex is a reliable and developer-friendly AI coding agent in your terminal. It can plan out and complete large tasks that span many files and steps.
Designed for real-world use-cases, Plandex can help you build a new app quickly, add new features to an existing codebase, write tests and scripts, understand code, fix bugs, and automatically debug failing commands (like tests, typecheckers, linters, etc.).
## Install 📥
```bash
curl -sL https://plandex.ai/install.sh | bash
```
**Note:** Windows is supported via [WSL](https://learn.microsoft.com/en-us/windows/wsl/install). Plandex only works correctly on Windows in the WSL shell. It doesn't work in the Windows CMD prompt or PowerShell.
[More installation options.](https://docs.plandex.ai/install)
## Hosting options ⚖️
| # | Option | Description |
|---|---------|--------------------------------|
| 1 | **Plandex Cloud (Integrated Models)** | No separate accounts or API keys are required. This is the quickest way to get started. If you choose this option, skip ahead to the [Get Started](#get-started-) section below. |
| 2 | **Plandex Cloud (BYO API Key)** | You'll need accounts and API keys for [OpenRouter.ai](https://openrouter.ai) and [OpenAI](https://platform.openai.com) to get started with the default models. |
| 3 | **Self-hosted** | First, follow the [self-hosting guide](./hosting/self-hosting.md) to set up your own Plandex server. You'll also need accounts and API keys for [OpenRouter.ai](https://openrouter.ai) and [OpenAI](https://platform.openai.com) to get started with the default models. |
If you're going with option 2 or 3 above, you'll need to set the `OPENROUTER_API_KEY` and `OPENAI_API_KEY` environment variables before continuing:
```bash
export OPENROUTER_API_KEY=...
export OPENAI_API_KEY=...
```
## Get started 🚀
Now `cd` into your **project's directory.** Make a new directory first with `mkdir your-project-dir` if you're starting on a new project.
```bash
cd your-project-dir
```
Then **start your first plan** with `plandex new`.
```bash
plandex new
```
☁️ *Note: if you're using Plandex Cloud, you'll be prompted at this point to start a trial.*
Load any relevant files, directories, directory layouts, urls, or images **into the LLM's context** with `plandex load`.
```bash
plandex load some-file.ts another-file.ts
plandex load src/components -r # load a whole directory
plandex load src --tree # load a directory layout (file names only)
plandex load src/**/*.ts # load files matching a glob pattern
plandex load https://raw.githubusercontent.com/plandex-ai/plandex/main/README.md # load the text content of a url
plandex load images/mockup.png # load an image
```
Now **send your prompt.** You can pass it in as a file:
```bash
plandex tell -f prompt.txt
```
Write it in vim:
```bash
plandex tell # tell with no arguments opens vim so you can write your prompt there
```
Or pass it inline (use enter for line breaks):
```bash
plandex tell "add a new line chart showing the number of foobars over time to components/charts.tsx"
```
Plandex will make a plan for your task and then implement that plan in code. **The changes won't yet be applied to your project files.** Instead, they'll accumulate in Plandex's sandbox.
**Note**: if you're not quite ready to give Plandex a task yet and want to ask questions or chat a bit first, you can use `plandex chat` instead of `plandex tell`. It works the same way, but it makes Plandex respond conversationally and prevents it from making any changes yet. Once you're ready, you can use `plandex tell` to go ahead with the implementation.
```bash
plandex chat "is it clear from the context how to add a new line chart?"
```
To learn about reviewing changes, iterating on the plan, and applying changes to your project, **[continue with the full quickstart.](https://docs.plandex.ai/quick-start#review-the-changes)**
## Docs 🛠️
### [👉 Full documentation.](https://docs.plandex.ai/)
## Build complex software with LLMs 🌟
⚡️ Changes are accumulated in a protected sandbox so that you can review them before automatically applying them to your project files. Built-in version control allows you to easily go backwards and try a different approach. Branches allow you to try multiple approaches and compare the results.
📑 Manage context efficiently in the terminal. Easily add files or entire directories to context, and keep them updated automatically as you work so that models always have the latest state of your project.
🧠 By default, Plandex uses (and is optimized for) a mix of Anthropic models (via OpenRouter.ai) and OpenAI models (via OpenAI's API). You can also use it with a wide range of other models from OpenRouter.ai or any other OpenAI-compatible provider.
✅ Plandex supports Mac, Linux, FreeBSD, and Windows. It runs from a single binary with no dependencies.
## Why Plandex? 🤔
🏗️ Go beyond autocomplete to build complex functionality with AI.
🚫 Stop the mouse-centered, copy-pasting madness of coding with ChatGPT or Claude.
⚡️ Ensure the model always has the latest versions of files in context.
🪙 Retain granular control over what's in the model's context and how many tokens you're using.
⏪ Rewind, iterate, and retry as needed until you get your prompt just right.
❤️🩹 Automatically debug failing commands (like tests, typecheckers, linters, etc.).
🌱 Explore multiple approaches with branches.
🔀 Run tasks in the background or work on multiple tasks in parallel.
🎛️ Try different models and temperatures, then compare results.
## Discussion and discord 💬
Please feel free to give your feedback, ask questions, report a bug, or just hang out:
- [Discord](https://discord.gg/plandex-ai)
- [Discussions](https://github.com/plandex-ai/plandex/discussions)
- [Issues](https://github.com/plandex-ai/plandex/issues)
## Contributors 👥
⭐️ Please star, fork, explore, and contribute to Plandex. There's a lot of work to do and so much that can be improved.
[Here's an overview on setting up a development environment.](https://docs.plandex.ai/development)
