Open source AI coding agent. Designed for large projects and real world tasks.
Go aiai-agentsai-developer-toolsai-toolsclicommand-linedeveloper-toolsgitgolanggpt-4llmopenaipolyglot-programmingterminalterminal-basedterminal-ui
docs: overhaul README with clearer structure and local mode emphasis
Dane Schneider00d3f1a70083
diff --git a/README.md b/README.mdindex 2a0981a3..9445e419 100644--- a/README.md+++ b/README.md@@ -30,7 +30,7 @@</a>·<a href="https://docs.plandex.ai/hosting/self-hosting">- <b>Self-Hosting</b>+ <b>Local Mode</b></a></p>@@ -61,43 +61,77 @@<br>-<h3 align="center">AI driven development in your terminal.<br/>Build entire features and apps with a robust workflow.</h3>+<h1 align="center" >+ Open source AI coding agent.<br/>+ For large tasks and real world projects.+</h1>+</small>-<br/>-<br/>+💻 Plandex is a terminal-based AI development tool that can **plan and execute** large coding tasks that span many steps and touch dozens of files.++🧠 Combine the best models from Anthropic, OpenAI, Google, and open source providers to build entire features and apps with a robust terminal-based workflow.++🚀 Plandex is capable of <strong>full autonomy</strong>—it can load relevant files, plan and implement changes, execute commands, and automatically debug—but it's also highly flexible and configurable, giving developers fine-grained control and a step-by-step review process when needed.++💪 Plandex is designed to be resilient to <strong>large projects and files</strong>. If you've found that others tools struggle once your project gets past a certain size or the changes are too complex, give Plandex a shot.++## Smart context management that works in big projects+* 🐘 **2M token effective context window** with default model pack. Plandex loads only what's needed for each step.+* 🗄️ **Reliable in large projects and files.** Easily generate, review, revise, and apply changes spanning dozens of files.+* 🗺️ **Fast project map generation** and syntax validation with tree-sitter. Supports 30+ languages.++## Tight control or full autonomy—it's up to you+* 🔬 **A cumulative diff review sandbox** keeps AI-generated changes from modifying your project until you approve them.+* 🚦 **Configurable autonomy:** go from full auto mode to fine-grained control depending on the task.+* 🐞 **Automated debugging** of terminal commands (like builds, linters, tests, deployments, and scripts).++## Tools that help you get production-ready results+* 💬 **A project-aware chat mode** that helps you flesh out ideas before moving to implementation. Also great for asking questions and learning about a codebase.+* 🧠 **Easily try + combine models** from multiple providers. Curated model packs offer different tradeoffs of capability, cost, and speed, as well as open source and provider-specific packs.+* 🔀 **Full-fledged version control** for every update to the plan, including branches for exploring multiple paths or comparing different models.+* 📂 **Git integration** with commit message generation and optional automatic commits.++## Dev-friendly, easy to install+* 🧑💻 **REPL mode** with fuzzy auto-complete for commands and file loading. Just run `plandex` in any project to get started.+* 🛠️ **CLI interface** for scripting or piping data into context.+* 📦 **One-line, zero dependency CLI install**. Dockerized local mode for easily self-hosting the server. Cloud-hosting options for extra reliability and convenience.+++<!-- <br/>+<br/> --><!-- Vimeo link is nicer on mobile than embedded video... downside is it navigates to vimeo in same tab (no way to add target=_blank) --><!-- https://github.com/plandex-ai/plandex/assets/545350/c2ee3bcd-1512-493f-bdd5-e3a4ca534a36 -->-<a href="https://player.vimeo.com/video/926634577">+<!-- <a href="https://player.vimeo.com/video/926634577"><img src="images/plandex-intro-vimeo.png" alt="Plandex intro video" width="100%"/>-</a>+</a> -->-<br/>-<br/>+<!-- <br/>+<br/> -->-## More examples 🎥+<!-- ## More examples 🎥<h4>👉 <a href="https://www.youtube.com/watch?v=0ULjQx25S_Y">Building Pong in C/OpenGL with GPT-4o and Plandex</a></h4><h4>👉 <a href="https://www.youtube.com/watch?v=rnlepfh7TN4">Fixing a tricky real-world bug in 5 minutes with Claude Opus 3 and Plandex</a></h4>-<br/>+<br/> -->-## Learn more about Plandex 🧐+<!-- ## Learn more 🧐-- [Overview](#overview-)-- [Install](#install)+<!-- - [Overview](#overview-) -->+<!-- - [Install](#install)- [Hosting options](#hosting-options-)- [Get started](#get-started-)- [Docs](https://docs.plandex.ai/)- [Build complex software](#build-complex-software-with-llms-)- [Why Plandex?](#why-plandex-)- [Discussion and discord](#discussion-and-discord-)-- [Contributors](#contributors-)+- [Contributors](#contributors-) --><br/>-## Overview 📚+<!-- ## Overview 📚<p>Churn through your backlog, work with unfamiliar technologies, get unstuck, and <strong>spend less time on the boring stuff.</strong></p>@@ -105,7 +139,11 @@<p>Designed for <strong>real-world use-cases</strong>, 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.). </p>-<br/>+<br/> -->++## Workflow 🔄++<img src="images/plandex-workflow.png" alt="Plandex workflow" width="100%"/>## Install 📥@@ -117,17 +155,18 @@ curl -sL https://plandex.ai/install.sh | bash[More installation options.](https://docs.plandex.ai/install)-<br/>-## Hosting options ⚖️+## Hosting ⚖️++| Option | Description |+|---------|--------------------------------|+| **Plandex Cloud (Integrated Models)** | • No separate accounts or API keys.<br/>• Easy multi-device usage.<br/>• Centralized billing and budgeting.<br/>• Quickest way to [get started.](https://app.plandex.ai/start?modelsMode=integrated) |+| **Plandex Cloud (BYO API Key)** | • Use Plandex Cloud with your own [OpenRouter.ai](https://openrouter.ai) and [OpenAI](https://platform.openai.com) keys.<br/> |+| **Self-hosted/Local Mode** | • Run Plandex locally with Docker or host on your own server.<br/>• Use your own [OpenRouter.ai](https://openrouter.ai) and [OpenAI](https://platform.openai.com) keys.<br/>• Follow the [local-mode quickstart](./hosting/self-hosting.md) to get started. |-| # | 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. |+## Provider keys 🔑-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:+If you're going with a 'BYO API Key' option above (whether cloud or self-hosted), you'll need to set the `OPENROUTER_API_KEY` and `OPENAI_API_KEY` environment variables before continuing:```bashexport OPENROUTER_API_KEY=...@@ -138,62 +177,33 @@ 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.+First, `cd` into a **project directory** where you want to get something done or chat about the project. Make a new directory first with `mkdir your-project-dir` if you're starting on a new project.```bashcd your-project-dir```--Then **start your first plan** with `plandex new`.+You might want to initialize a git repository if you haven't already. Plandex integrates nicely with git, though it's not required.```bash-plandex new+git init```-☁️ *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`.+Now start the Plandex REPL in your project:```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+plandex```--Now **send your prompt.** You can pass it in as a file:+or for short:```bash-plandex tell -f prompt.txt+pdx```+☁️ *If you're using Plandex Cloud, you'll be prompted at this point to start a trial.*-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)**+Now just give a quick the REPL help text a quick read, and you're ready go.<br/>@@ -201,33 +211,6 @@ To learn about reviewing changes, iterating on the plan, and applying changes to### [👉 Full documentation.](https://docs.plandex.ai/)--<br/>--## 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.--<br/>--## Why Plandex? 🤔--🏗️ Go beyond autocomplete to build complex functionality with AI.<br>-🚫 Stop the mouse-centered, copy-pasting madness of coding with ChatGPT or Claude.<br>-⚡️ Ensure the model always has the latest versions of files in context.<br>-🪙 Retain granular control over what's in the model's context and how many tokens you're using.<br>-⏪ Rewind, iterate, and retry as needed until you get your prompt just right.<br>-❤️🩹 Automatically debug failing commands (like tests, typecheckers, linters, etc.).<br>-🌱 Explore multiple approaches with branches.<br>-🔀 Run tasks in the background or work on multiple tasks in parallel.<br>-🎛️ Try different models and temperatures, then compare results.<br>-<br/>## Discussion and discord 💬@@ -238,6 +221,12 @@ Please feel free to give your feedback, ask questions, report a bug, or just han- [Discussions](https://github.com/plandex-ai/plandex/discussions)- [Issues](https://github.com/plandex-ai/plandex/issues)+## Follow and subscribe++- [Follow @PlandexAI](https://x.com/PlandexAI)+- [Follow @Danenania](https://x.com/Danenania) (Plandex's creator)+- [Subscribe on YouTube](https://x.com/PlandexAI)+<br/>## Contributors 👥