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 and README updates
Dane Schneider5d8ce315cd4b
diff --git a/README.md b/README.mdindex eacdaed7..42a6dd3e 100644--- a/README.md+++ b/README.md@@ -32,19 +32,6 @@<a href="https://docs.plandex.ai/hosting/self-hosting"><b>Self-Hosting</b></a>- <!-- ·- <a href="./guides/DEVELOPMENT.md">- <b>Development</b>- </a> -->- <!-- ·- <a href="https://discord.gg/plandex-ai">- <b>Discord</b>- </a>- ·- <a href="#weekly-office-hours-">- <b>Office Hours</b>- </a>- --></p><br>@@ -101,11 +88,11 @@- [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-)-- [Roadmap](#roadmap-%EF%B8%8F)- [Discussion and discord](#discussion-and-discord-)- [Contributors](#contributors-)<br/>@@ -116,7 +103,7 @@<p>Plandex is a <strong>reliable and developer-friendly</strong> AI coding agent in your terminal. It can plan out and complete <strong>large tasks</strong> that span many files and steps.</p>-<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, and fix bugs. </p>+<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/>@@ -132,16 +119,22 @@ curl -sL https://plandex.ai/install.sh | bash<br/>-## Get started 🚀+## Hosting options ⚖️-Plandex uses OpenAI by default. If you don't have an OpenAI account, first [sign up here.](https://platform.openai.com/signup)+| # | 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. |-Then [generate an API key here](https://platform.openai.com/account/api-keys) and `export` it.+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.@@ -156,6 +149,7 @@ Then **start your first plan** with `plandex new`.plandex new```+☁️ 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`.@@ -191,6 +185,12 @@ plandex tell "add a new line chart showing the number of foobars over time to coPlandex 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)**<br/>@@ -208,7 +208,7 @@ To learn about reviewing changes, iterating on the plan, and applying changes to📑 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 relies on the OpenAI API and requires an `OPENAI_API_KEY` environment variable. You can also use it with a wide range of other models, including Anthropic Claude, Google Gemini, Mixtral, Llama and many more via OpenRouter.ai, Together.ai, or any other OpenAI-compatible provider.+🧠 By default, Plandex uses a mix of Anthropic models (via OpenRouter.ai) and OpenAI models. You can also use it with a wide range of other models from any OpenAI-compatible provider.✅ Plandex supports Mac, Linux, FreeBSD, and Windows. It runs from a single binary with no dependencies.@@ -221,31 +221,16 @@ To learn about reviewing changes, iterating on the plan, and applying changes to⚡️ 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/>-## Roadmap 🗺️--🧠 Support for open source models, Google Gemini, and Anthropic Claude in addition to OpenAI ✅ released<br>-🖼️ Support for multi-modal models—add images and screenshots to context ✅ released<br>-🤝 Plan sharing and team collaboration<br>-🖥️ VSCode and JetBrains extensions<br>-📦 Community plugins and modules<br>-🔌 Github integration<br>-🌐 Web dashboard and GUI<br>-🔐 SOC2 compliance<br>-🛩️ Fine-tuned models<br>--This list will grow and be prioritized based on your feedback.--<br/>-## Discussion and discord 💬-Speaking of feedback, feel free to give yours, ask questions, report a bug, or just hang out:+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)@@ -257,8 +242,6 @@ Speaking of feedback, feel free to give yours, ask questions, report a bug, or j⭐️ Please star, fork, explore, and contribute to Plandex. There's a lot of work to do and so much that can be improved.-Work on tests, evals, prompts, and bug fixes is especially appreciated.-[Here's an overview on setting up a development environment.](https://docs.plandex.ai/development)diff --git a/docs/docs/cli-reference.md b/docs/docs/cli-reference.mdindex 38945cc9..3fbb838b 100644--- a/docs/docs/cli-reference.md+++ b/docs/docs/cli-reference.md@@ -213,7 +213,7 @@ plandex clear### tell-Describe a task, ask a question, or chat.+Describe a task.```bashplandex tell -f prompt.txt # from file@@ -231,6 +231,12 @@ pdx t # alias`--bg`: Run task in the background.+`--yes/-y`: Automatically confirm context updates.++`--apply/-a`: Automatically apply changes (and confirm context updates).++`--commit/-c`: Commit changes to git when `--apply/-a` is passed.+### continueContinue the plan.@@ -247,6 +253,12 @@ pdx c # alias`--bg`: Run task in the background.+`--yes/-y`: Automatically confirm context updates.++`--apply/-a`: Automatically apply changes (and confirm context updates).++`--commit/-c`: Commit changes to git when `--apply/-a` is passed.+### buildBuild any unbuilt pending changes from the plan conversation.@@ -258,18 +270,53 @@ pdx b # alias`--bg`: Build in the background.+`--yes/-y`: Automatically confirm context updates.++`--apply/-a`: Automatically apply changes (and confirm context updates).++`--commit/-c`: Commit changes to git when `--apply/-a` is passed.++### chat++Ask a question or chat without making any changes.++```bash+plandex chat "is it clear from the context how to add a new line chart?"+```++`--file/-f`: File path containing prompt.++`--yes/-y`: Automatically confirm context updates.++### debug++Repeatedly run a command and auto-apply fixes until it succeeds. Defaults to 5 tries before giving up.++```bash+plandex debug 'npm test' # try 5 times or until it succeeds+plandex debug 10 'npm test' # try 10 times or until it succeeds+pdx db 'npm test' # alias+```++`--commit/-c`: Commit changes to git on each try.+## Changes### diff-Review pending changes in 'git diff' format.+Review pending changes in 'git diff' format or in a local browser UI.```bashplandex diff+plandex diff --ui````--plain/-p`: Output diffs in plain text with no ANSI codes.+`--ui/-u`: Review pending changes in a local browser UI.++`--side-by-side/-s`: Show diffs UI in side-by-side view rather than line-by-line.+### changesReview pending changes in a TUI.@@ -289,6 +336,10 @@ pdx ap # alias`--yes/-y`: Skip confirmation.+`--commit/-c`: Commit changes to git.++`--no-commit/-n`: Don't commit changes to git.+### rejectReject pending changes to one or more project files.@@ -569,7 +620,9 @@ Sign in, accept an invite, or create an account.plandex sign-in```-Plandex will prompt you for all required information to sign in, accept an invite, or create an account.+`--code/-c`: Sign in with a code from the Plandex Cloud web UI.++Unless you pass `--code/-c` (from the Plandex Cloud web UI), Plandex will prompt you for all required information to sign in, accept an invite, or create an account.### invite@@ -599,3 +652,28 @@ List users and pending invites in your org.plandex users```+## Plandex Cloud++### billing++Show the billing settings page.++```bash+plandex billing+```++### credits++Show your current credits balance.++```bash+plandex credits+```++### credits log++Show the credits usage log, including all model calls and responses.++```bash+plandex credits log+```diff --git a/docs/docs/core-concepts/context-management.md b/docs/docs/core-concepts/context-management.mdindex 27f81fd5..bedfaea1 100644--- a/docs/docs/core-concepts/context-management.md+++ b/docs/docs/core-concepts/context-management.md@@ -130,7 +130,7 @@ plandex clear## Updating Context-If files in context are modified outside of Plandex, you will be prompted to update them the next time you send a prompt. You can also update any outdated files with the `update` command.+If files, directory layouts, or URLs in context are modified outside of Plandex, you'll be prompted to update them the next time you send a prompt. You can also update any outdated files with the `update` command.```bashplandex update # update files in contextdiff --git a/docs/docs/core-concepts/conversations.md b/docs/docs/core-concepts/conversations.mdindex 0c489c3e..6688fafc 100644--- a/docs/docs/core-concepts/conversations.md+++ b/docs/docs/core-concepts/conversations.md@@ -33,6 +33,8 @@ plandex convo 2- # show messages 2 through the end of the conversationEvery time the AI model replies, Plandex will summarize the conversation so far in the background and store the summary in case it's needed later. When the conversation size in tokens exceeds the model's limit, Plandex will automatically replace some number of older messages with the corresponding summary. It will summarize as many messages as necessary to keep the conversation size under the limit.+Summaries are also used by the model as a form of working memory to keep track of the state of the plan—what's been implemented and what remains to be done.+You can see the latest summary with the `summary` command.```bashdiff --git a/docs/docs/core-concepts/debugging-commands.md b/docs/docs/core-concepts/debugging-commands.mdnew file mode 100644index 00000000..ddf61969--- /dev/null+++ b/docs/docs/core-concepts/debugging-commands.md@@ -0,0 +1,65 @@+---+sidebar_position: 9+sidebar_label: Auto-Debug Terminal Commands+---++# Auto-Debug Terminal Commands++As of version 2.0.0, Plandex includes a powerful new `plandex debug` command that can repeatedly run any terminal command, continually making fixes based on the command's output until it succeeds.++## Using `plandex debug`++To use `plandex debug`, simply run it with the command you want to debug:++```bash+plandex debug 'npm test'+```++This is a shortcut for:++1. Running a shell command and checking whether it succeeds or fails.+2. If it fails, send the exit code and command output to `plandex tell`.+3. Run `plandex apply` to apply the suggested fixes.+4. Repeat until the command succeeds.++## Number of Tries++By default, `plandex debug` will run the command up to 5 times before giving up. You can change this by providing a different number of tries as the first argument:++```bash+plandex debug 10 'npm test'+```++## Auto-Commit++By default, `plandex debug` will not commit the changes it makes to git. If you want to automatically commit the changes after each try with an auto-generated commit message, you can use the `--commit\-c` flag:++```bash+plandex debug -c 'npm test' # will commit changes after each try+```++## Commands That Succeed++If a command succeeds on the first try, `plandex debug` will exit immediately without making any model calls, so you can use it for commands that may or may not succeed on the first try.++```bash+plandex debug "echo 'ok'" # succeeds and immediately exits+```++## Be Careful!!++`plandex debug` is a powerful tool, but it should be used with care. Because it applies changes automatically and repeatedly without a review step, it can quickly make a large number of changes to your project. Before using it, it's a good idea to make sure you have a clean git state so that you can easily revert the changes if something goes wrong.++You should also be careful when using `plandex debug` with commands that may have side effects. Always test commands manually first to make sure they work as expected.++If possible, try to make the commands you give to `plandex debug` *idempotent*, meaning that they're safe to run multiple times. For example, if you have a deploy script, you'd want to be sure that it cleans up after itself if it fails halfway through so that you don't end up with a partially deployed system.++## Alternative: Piping Into `plandex tell`++For a less automated approach that can accomplish the same thing, you can run your command and then pipe its output into `plandex tell`:++```bash+npm test | plandex tell 'npm test output'+```++This will work similarly to `plandex debug`, but without the automatic retries and changes. You can review the changes and then run `plandex apply` if you're happy with them.diff --git a/docs/docs/core-concepts/orgs.md b/docs/docs/core-concepts/orgs.mdindex 5881562e..3c634df2 100644--- a/docs/docs/core-concepts/orgs.md+++ b/docs/docs/core-concepts/orgs.md@@ -1,5 +1,5 @@----sidebar_position: 9+sidebar_position: 10sidebar_label: Collaboration / Orgs---diff --git a/docs/docs/core-concepts/prompts.md b/docs/docs/core-concepts/prompts.mdindex 63d81d84..de84bcd0 100644--- a/docs/docs/core-concepts/prompts.md+++ b/docs/docs/core-concepts/prompts.md@@ -33,10 +33,10 @@ You can also pipe in the results of another command:git diff | plandex tell```-When you pipe in results like this, you can also supply an inline string to give a lbel or additional context to the results:+When you pipe in results like this, you can also supply an inline string to give a label or additional context to the results:```bash-git diff | plandex tell 'git diff output'+git diff | plandex tell "'git diff' output"```## Plan Stream TUI@@ -83,18 +83,28 @@ By default, `plandex tell` opens the plan stream TUI and streams Plandex's respoYou can learn more about using and interacting with background tasks [here](./background-tasks.md).+## Keeping Context Updated++When you send a prompt, whether through `plandex tell` or `plandex chat`, Plandex will check whether the content of any files, directory layouts, or URLs you've loaded into context have changed. If so, you'll be prompted to update the context before continuing.++If you want to automatically update context without being prompted, you can pass the `--yes/-y` flag to `plandex tell` or `plandex continue`:++```bash+plandex tell -y "add a cancel button to the foobars form in src/components/foobars-form.tsx"+```+## Building FilesAs Plandex implements your task, files it creates or updates will appear in the `Building Plan` section of the plan stream TUI. Plandex will **build** all changes proposed by the plan into a set of pending changesets for each affected file.-Keep in mind that initially, these changes **will not** be directly applied to your project files. Instead, they will be **pending** in Plandex's version-controlled sandbox. This allows you to review the proposed changes or continue iterating and accumulating more changes. You can view the pending changes with `plandex diff` (for git diff format) or `plandex changes` (to view them in a TUI). Once you're happy with the changes, you can apply them to your project files with `plandex apply`.+Keep in mind that initially, these changes **will not** be directly applied to your project files. Instead, they will be **pending** in Plandex's version-controlled sandbox. This allows you to review the proposed changes or continue iterating and accumulating more changes. You can view the pending changes with `plandex diff` (for git diff format in the terminal) or `plandex diff --ui` (to view them in a local browser UI). Once you're happy with the changes, you can apply them to your project files with `plandex apply`.- [Learn more about reviewing changes.](./reviewing-changes.md)- [Learn more about version control.](./version-control.md)### Skipping builds / `plandex build`-You can skip building files when you send a prompt by passing the `--no-build` flag to `plandex tell` or `plandex continue`. This can be useful if you want to ensure that a plan is on the right track before comitting the time and tokens to build files.+You can skip building files when you send a prompt by passing the `--no-build` flag to `plandex tell` or `plandex continue`. This can be useful if you want to ensure that a plan is on the right track before building files.```bashplandex tell "implement sign up and sign in forms in src/components" --no-build@@ -127,6 +137,22 @@ plandex tell "now implement the UI portion of the forgot password flow"# the above will start building the changes proposed in the earlier prompt that was passed --no-build```+## Automatically Applying Changes++If you want Plandex to *automatically* apply changes when a plan is complete, you can pass the `--apply/-a` flag to `plandex tell`, `plandex continue`, or `plandex build`:++```bash+plandex tell "add a new route for updating notification settings to src/routes.ts" --apply+```++The `--apply/-a` flag will also automatically update context if needed, just as the `--yes/-y` flag does.++When passing `--apply/-a`, you can also use the `--commit/-c` flag to commit the changes to git with an auto-generated commit message. This will only commit the specific changes that were made by the plan. Any other changes in your git repository, staged or unstaged, will remain as they are.++```bash+plandex tell "add a new route for updating notification settings to src/routes.ts" --apply --commit+```+## Iterating on a PlanIf you send a prompt:diff --git a/docs/docs/core-concepts/reviewing-changes.md b/docs/docs/core-concepts/reviewing-changes.mdindex 60b842d6..6633ae94 100644--- a/docs/docs/core-concepts/reviewing-changes.md+++ b/docs/docs/core-concepts/reviewing-changes.md@@ -5,9 +5,9 @@ sidebar_label: Pending Changes# Pending Changes-When you give Plandex a task, the changes aren't applied directly to your project files. Instead, they are accumulated in Plandex's version-controlled **sandbox** so that you can review them first.+When you give Plandex a task, by default the changes aren't applied directly to your project files. Instead, they are accumulated in Plandex's version-controlled **sandbox** so that you can review them first.-## `plandex diffs` / Changes TUI+## `plandex diffs` / `plandex diffs --ui`When Plandex has finished with your task, you can review the proposed changes with the `plandex diff` command, which shows them in `git diff` format:@@ -17,23 +17,29 @@ plandex diff`--plain/-p`: Outputs the conversation in plain text with no ANSI codes.-You can also view them in Plandex's changes TUI:+You can also view them in a local browser UI with the `plandex diffs --ui` command:```bash-plandex changes+plandex diffs --ui```+If you pass the `--side-by-side/-s` flag alongside `--ui`, the diffs will be shown in a side-by-side view rather than line-by-line.+## Rejecting FilesWhile we're working hard to make file updates as reliable as possible, bad updates can still happen. If the plan's changes were applied incorrectly to a file, you can either [apply the changes](#apply-the-changes) and then fix the problems manually, *or* you can reject the updates to that file and then make the proposed changes yourself manually.-To reject changes to a file (or multiple files), you can run `plandex reject` with one ore more file paths:+To reject changes to a file (or multiple files), you can run `plandex reject` with one or more file paths:```bash-plandex reject+plandex reject some-file.py```-You can also reject changes using the `r` hotkey in the `plandex changes` TUI.+You can reject *all* currently pending files by passing no arguments to the reject command (you'll then be prompted to confirm the rejection):++```bash+plandex reject+```Once the bad update is rejected, copy the changes from the plan's output or run `plandex convo` to output the full conversation and copy them from there. Then apply the updates to that file yourself.@@ -47,4 +53,14 @@ plandex applyIf you're in a git repository, Plandex will give you the option of grouping the changes into a git commit with an automatically generated commit message. Any uncommitted changes that were present in your working directory beforehand will be unaffected.-You can skip the `plandex apply` confirmation with the `-y` flag.\ No newline at end of file+You can skip the `plandex apply` confirmation with the `-y` flag.++You can pass the `--commit/-c` flag to commit the changes to git after applying them without confirmation.++You can pass the `--no-commit/-n` flag to prevent the changes from being committed to git after applying them without confirmation.++## Auto-Applying Changes++If you want to skip the review step and automatically apply the changes from a plan immediately after it's complete, you can pass the `--apply/-a` flag to `plandex tell`, `plandex continue`, or `plandex build`.++If you do this, you can also pass the `--commit/-c` flag to commit the automatically applied changes to git.\ No newline at end of filediff --git a/docs/docs/development.md b/docs/docs/development.mdindex 17255002..1f8734c4 100644--- a/docs/docs/development.md+++ b/docs/docs/development.md@@ -7,7 +7,7 @@ sidebar_label: DevelopmentTo set up a development environment, first install dependencies:-- Go 1.21.3 - [install here](https://go.dev/doc/install)+- Go 1.23.3 - [install here](https://go.dev/doc/install)- [reflex](https://github.com/cespare/reflex) 0.3.1 - for watching files and rebuilding in development. Install with `go install github.com/cespare/[email protected]`- PostgreSQL 14 - https://www.postgresql.org/download/diff --git a/docs/docs/environment-variables.md b/docs/docs/environment-variables.mdindex d301442a..99aeeca6 100644--- a/docs/docs/environment-variables.md+++ b/docs/docs/environment-variables.md@@ -19,13 +19,13 @@ PLANDEX_API_HOST= # Defaults to 'http://localhost:8080' if PLANDEX_ENV is develo### LLM Providers```bash-OPENAI_API_BASE= # Your OpenAI server, such as http://localhost:1234/v1 Defaults to empty.-OPENAI_API_KEY= # Your OpenAI key.--# optional - set API keys for any other providers you're using-export OPENROUTER_API_KEY= # Your OpenRouter.ai API key.-export TOGETHER_API_KEY = # Your Together.ai API key.+OPENAI_API_KEY= # Your OpenAI key (if self-hosting or using BYO API Key mode with Plandex Cloud)+OPENROUTER_API_KEY= # Your OpenRouter.ai API key (if self-hosting or using BYO API Key mode with Plandex Cloud)+TOGETHER_API_KEY = # Your Together.ai API key (if self-hosting or using BYO API Key mode with Plandex Cloud)# etc.++OPENAI_API_BASE= # Your OpenAI server, such as http://localhost:1234/v1 Defaults to empty.+OPENAI_ORG_ID= # Your OpenAI organization ID. Defaults to empty.```### Upgradesdiff --git a/docs/docs/hosting/cloud.md b/docs/docs/hosting/cloud.mdindex 83d2c8fd..936febf6 100644--- a/docs/docs/hosting/cloud.md+++ b/docs/docs/hosting/cloud.md@@ -7,9 +7,40 @@ sidebar_label: Cloud## Overview-Plandex Cloud is the easiest and most reliable way to use Plandex. You'll be prompted to start an anonymous trial (no email required) when you create your first plan with `plandex new`. Trial accounts are limited to 10 plans and 10 AI model replies per plan. You can upgrade to an unlimited account with your name and email.+Plandex Cloud is the easiest and most reliable way to use Plandex. You'll be prompted to start a trial when you create your first plan with `plandex new`.-Plandex Cloud accounts are free for now. In the future, they will cost somewhere in the $10-20 per month range.+## Billing Modes++Plandex Cloud has two billing modes:++### Integrated Models++- Use Plandex credits to pay for AI models.+- No separate accounts or API keys are required.+- Credits are deducted at the model's price from OpenAI or OpenRouter.ai plus a small markup to cover credit card processing costs.+- Start with a $5 trial (includes $5 in credits).+- After the trial, you can upgrade to a paid plan for $25 per month—includes $10 in credits every month that never expire.++### BYO API Key++- Use your own OpenAI, OpenRouter.ai, or other OpenAI-compatible provider accounts.+- Supply your own API keys.+- Start with a free trial up to 10 plans and 15 model responses per plan.+- After the trial, you can upgrade to a paid plan for $20 per month.++## Billing Settings++Run `plandex billing` in the terminal to bring up the billing settings page in your default browser, or go to [https://app.plandex.ai/settings/billing](https://app.plandex.ai/settings/billing) (sign in if necessary).++Here you can switch billing modes, view your current plan, manage your billing details, and pause or cancel your subscription.++## Integrated Models Mode++If you're using **Integrated Models Mode**, you can use the billing settings page to view your credits balance, purchase credits, and configure auto-recharge settings to automatically add credits to your account when your balance gets too low. You can also set a monthly budget and an email notification threshold.++You can also see your credits balance in the terminal with `plandex credits`.++You can see a full history of your usage that includes every model call and response with `plandex credits log`.## Privacy / Data Retention@@ -19,11 +50,13 @@ That said, if you delete a plan or delete your Plandex Cloud account, all associData sent to Plandex Cloud may be shared with the following third parties:+- [OpenAI](https://openai.com) for OpenAI models when using Integrated Models Mode.+- [OpenRouter.ai](https://openrouter.ai/) for Anthropic, Google, and other non-OpenAI models when using Integrated Models Mode.- [AWS](https://aws.amazon.com/) for hosting and database services. Data is encrypted in transit and at rest.- Your name and email is shared with [Loops](https://loops.so/), an email marketing service, in order to send you updates on Plandex. You can opt out of these emails at any time with one click.-- When billing and payments are implemented, your name and email may be shared with our payment processor [Stripe](https://stripe.com/).-- In the future, your name, email, and metadata on the actions you take with Plandex may be shared with a third party analytics service in order to track usage and make improvements.+- Your name and email are shared with our payment processor [Stripe](https://stripe.com/) if you subscribe to a paid plan or purchase the $5 trial.+- Usage data is sent to [Google Analytics](https://analytics.google.com/) to help us track usage and make improvements.-Apart from the above list, no other data will be shared with any other third party. The list will be updated when a specific third party is chosen for any of the above services, or if any new third party services are introduced.+Apart from the above list, no other data will be shared with any other third party. The list will be updated if any new third party services are introduced.-Data sent to a model provider like OpenAI is subject to the model provider's privacy and data retention policies.\ No newline at end of file+Data sent to a model provider like OpenAI or OpenRouter.ai is subject to the model provider's privacy and data retention policies.\ No newline at end of filediff --git a/docs/docs/intro.md b/docs/docs/intro.mdindex 84831658..a539260c 100644--- a/docs/docs/intro.md+++ b/docs/docs/intro.md@@ -21,7 +21,8 @@ It combines multiple agents to complete tasks that span many files and model res- Refactor.- Work with unfamiliar technologies.- Ask questions about code.-- Understand a codebase.+- Understand a codebase.+- Auto-debug a failing shell command (tests, type checks, scripts, etc.).## What makes Plandex different?@@ -41,24 +42,15 @@ Apart from version control, Plandex also helps you manage what's in the LLM's co- Files you add to context are kept up-to-date automatically so that the LLM is always using the latest version.- Unlike IDE-based tools that automatically and opaquely load context in the background, Plandex gives the developer precise control of what's in the LLM's context. You never have to wonder what's been loaded or whether it's up-to-date. This is crucial to getting good results and keeping a handle on costs, particularly when you want to go beyond auto-complete and work on larger tasks.-## Focus+### Automated Debugging-For now, Plandex is focused on:--1. Planning out the changes needed to complete a task.-2. Creating or updating all the necessary files to complete that task.--It doesn't yet do automatic execution of code or automatic selection of context—both are left to the developer.--In other words, Plandex isn't (yet) shooting for full autonomy. While we do plan to move in this direction over time, we think the current level of model capabilities make Plandex's focus a sweet spot for achieving real productivity gains.--Though full autonomy is certainly an enticing prospect, in practice it often means wasting a lot of time and tokens letting the LLM spin its wheels on problems that are trivial for a developer to identify and fix. You can definitely use Plandex to help debug its own code, but for now we think it's best to make this opt-in rather than the default behavior.+Plandex can repeatedly run a failing terminal command, continually making fixes based on the command's output and retrying until it succeeds.## Models-Plandex uses OpenAI models by default, as so far we've found them to offer the best balance between intelligence and reliability.+By default, Plandex uses a combination of Anthropic and OpenAI models; Anthropic models are served via OpenRouter.ai and OpenAI models are served directly from OpenAI.-That said, you can also use it with a wide range of other models, including Anthropic Claude, Google Gemini, Mixtral, Llama and many more via OpenRouter.ai, Together.ai, or any other OpenAI-compatible provider.+That said, you can also use it with a wide range of other models from any OpenAI-compatible provider.## Languages and Platformsdiff --git a/docs/docs/models/model-providers.md b/docs/docs/models/model-providers.mdindex 74d7d490..be7aa2af 100644--- a/docs/docs/models/model-providers.md+++ b/docs/docs/models/model-providers.md@@ -5,15 +5,31 @@ sidebar_label: Providers# Model Providers-By default, Plandex uses OpenAI models, but you can use models from any provider that provides an OpenAI-compatible API, like [OpenRouter.ai](https://openrouter.ai/) (Anthropic, Gemini, and open source models), [Together.ai](https://together.ai) (open source models), [Replicate](https://replicate.com/), [Ollama](https://ollama.com/), and more.+By default, Plandex uses a mix of Anthropic models (via OpenRouter.ai) and OpenAI models, but you can use models from any provider that provides an OpenAI-compatible API, like [OpenRouter.ai](https://openrouter.ai/) (Anthropic, Gemini, and open source models), [Together.ai](https://together.ai) (open source models), [Replicate](https://replicate.com/), [Ollama](https://ollama.com/), and more.## Limitations-While you can use Plandex with many different providers and models as described above, Plandex requires reliable function calling, which can still be a challenge to find in non-OpenAI models. Additionally, Plandex's prompts have mainly been written and tested against OpenAI models.+While you can use Plandex with many different providers and models as described above, some crucial Plandex [roles](./roles.md) require reliable function calling, which can still be a challenge to find in open source models. Additionally, Plandex's prompts have mainly been written and tested against Anthropic and OpenAI models.-For these reasons, OpenAI models will tend to provide the best experience, and it's recommended to start with the defaults.+For these reasons, the default mix of Anthropic and OpenAI models will tend to provide the best experience, so it's recommended to start with the defaults.-In the future, we plan to offer prompts that are tailored for different models, and we also expect that other models and providers will catch up on the reliability front. Until then, **support for non-OpenAI models should generally be considered experimental.**+In the future, we plan to offer prompts that are tailored for different models, and we also expect that other models and providers will catch up on the reliability front. Until then, **support for non-default models should generally be considered experimental.**++## Integrated Models++If you use [Plandex Cloud](../hosting/cloud.md), you have the option of using **Integrated Models Mode** which allows you to use Plandex credits to pay for AI models. No separate accounts or API keys are required in this case.++If, alternatively, you use **BYO API Key Mode** with Plandex Cloud, or if you self-host Plandex, you'll need to generate API keys for the providers you want to use.++## OpenRouter++### Account++If you don't have an OpenRouter account, first [sign up here.](https://openrouter.ai/signup)++### API Key++Once you've created an OpenRouter account, [generate an API key here.](https://openrouter.ai/keys)## OpenAI@@ -27,21 +43,21 @@ Once you've created an OpenAI account, [generate an API key here.](https://platf## Other Providers-Plandex can use models from any provider that is compatible with the OpenAI API, like OpenRouter.ai (Anthropic, Gemini, and open source models), Together.ai (open source models), Replicate, Ollama, and more. You'll need to create an account and generate an API key for any other providers you plan on using.+Apart from those listed above,Plandex can use models from any provider that is compatible with the OpenAI API, like Together.ai, Replicate, Ollama, and more. You'll need to create an account and generate an API key for any other providers you plan on using.## Environment Variables-Now that you've generated an API key, export it as an environment variable in your terminal.+Now that you've generated API keys for your providers, export them as environment variables in your terminal.```bash+export OPENROUTER_API_KEY=...export OPENAI_API_KEY=...# optional - set api keys for any other providers you're using-export OPENROUTER_API_KEY=...export TOGETHER_API_KEY...```-If you're using OpenAI as your model provider, you can also set a different base URL for API calls:+If you're using OpenAI as a model provider, you can also set a different base URL for API calls:```bashexport OPENAI_API_BASE=... # optional - set a different base url for OpenAI calls e.g. https://<your-proxy>/v1diff --git a/docs/docs/models/roles.md b/docs/docs/models/roles.mdindex 42e77a02..69f74d52 100644--- a/docs/docs/models/roles.md+++ b/docs/docs/models/roles.md@@ -17,7 +17,6 @@ Requires streaming support.Summarizes conversations to stay under the limit set in `max-convo-tokens`. Also keeps track of the status of a plan to help determine whether it's finished or should continue (in conjunction with the `auto-continue` role).-### `auto-continue`Determines whether a plan is finished or should automatically continue based on the previous response and the `summarizer` role's latest summary.@@ -28,20 +27,22 @@ Requires function calling support.Builds the proposed changes described by the `planner` role into pending file updates.-Requires function calling support.--### `verifier`+### `verifier`Verifies correctness of file updates produced by the `builder` role. Defaults to the same model and settings as the `builder` role.Requires function calling support.+Note: as of v2.0.0, the `verifier` role is only used for languages without tree-sitter support. You can see the list of languages with tree-sitter support [here](https://github.com/plandex-ai/plandex/blob/main/app/server/syntax/parsers.go).+### `auto-fix`Fixes syntax errors, as well as other problems identified by the `verifier` role. Defaults to the same model and settings as the `builder` role.Requires function calling support.+Note: as of v2.0.0, the `auto-fix` role is only used for languages without tree-sitter support. You can see the list of languages with tree-sitter support [here](https://github.com/plandex-ai/plandex/blob/main/app/server/syntax/parsers.go).+### `names`Gives automatically-generated names to plans and context.diff --git a/docs/docs/quick-start.md b/docs/docs/quick-start.mdindex b2bf14bf..eb5fe3aa 100644--- a/docs/docs/quick-start.md+++ b/docs/docs/quick-start.md@@ -15,14 +15,20 @@ curl -sL https://plandex.ai/install.sh | bashNote that Windows is supported via [WSL](https://learn.microsoft.com/en-us/windows/wsl/about). Plandex only works correctly on Windows in the WSL shell. It doesn't work in the Windows CMD prompt or PowerShell.+## Decide How To Use Plandex-## Set `OPENAI_API_KEY`+Choose from three options:-Plandex uses OpenAI by default. If you don't have an OpenAI account, first [sign up here.](https://platform.openai.com/signup)+| # | 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 [Create A Plan](#create-a-plan) 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. |-Then [generate an API key here](https://platform.openai.com/account/api-keys) and `export` it.+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=...```@@ -52,6 +58,8 @@ Now **create your first plan** with `plandex new`.plandex new```+If you're using Plandex Cloud, you'll be prompted at this point to start a trial.+## Load In ContextLoad any relevant files, directories, directory layouts, urls, or images **into the LLM's context** with `plandex load`. You can also pipe in the results of a command.@@ -86,7 +94,13 @@ Or pass it inline (use enter for line breaks):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.+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?"+```## Review The Changes@@ -96,10 +110,10 @@ When Plandex has finished with your task, you can review the proposed changes wiplandex diff```-Or you can view them in Plandex's changes TUI:+Or you can view them in a local browser UI:```bash-plandex changes+plandex diff --ui```## Iterate If Needed@@ -132,8 +146,6 @@ To reject changes to a file (or multiple files), you can run `plandex reject` wiplandex reject components/charts.tsx```-You can also reject changes using the `r` hotkey in the `plandex changes` TUI.-Once the bad update is rejected, copy the changes from the plan's output or run `plandex convo` to output the full conversation and copy them from there. Then apply the updates to that file yourself.## Apply The Changes@@ -146,7 +158,23 @@ plandex applyIf you're in a git repository, Plandex will give you the option of grouping the changes into a git commit with an automatically generated commit message.-You've now experienced the core workflow of Plandex! While there are more commands and options available, those described above are what you'll be using most often.+## Auto-Debug Problems++If you have a test suite, type checker, or start command that's failing after you apply the changes, you can use the `plandex debug` command to send the output to Plandex and ask it to automatically fix the problem(s).++```bash+plandex debug 'npm test'+```++This will make Plandex run the given command, send the output to the LLM, attempt a fix, apply the changes, and then run the command again to verify that the problem is fixed. By default, Plandex will try up to 5 times before giving up, but you can also specify the number of tries like this:++```bash+plandex debug 10 'npm test' # try 10 times+```++---++**You've now experienced the core workflow of Plandex!** While there are more commands and options available, those described above are what you'll be using most often.## CLI Help@@ -164,11 +192,13 @@ Here are the same commands we went through above using aliases to minimize typinpdx newpdx l some-file.ts another-file.ts # loadpdx t -f prompt.txt # tell+plandex chat "is it clear from the context how to add a new line chart?"pdx diff-pdx ch # changes+pdx diff --uipdx logpdx rw e7e06e0 # rewindpdx c # continuepdx rj components/charts.tsx # rejectpdx ap # apply+pdx db 'npm test' # debug```\ No newline at end of filediff --git a/docs/docs/security.md b/docs/docs/security.mdindex 7bf57c2f..d14a6929 100644--- a/docs/docs/security.md+++ b/docs/docs/security.md@@ -10,6 +10,8 @@ Plandex respects `.gitignore` and won't load any files that you're ignoring unle## API Key Security-Plandex is a bring-your-own-API-key tool. On the Plandex server, whether that's Plandex Cloud or a self-hosted server, API keys are only stored ephemerally in RAM while they are in active use. They are never written to disk, logged, or stored in a database. As soon as a plan stream ends, the API key is removed from memory and no longer exists anywhere on the Plandex server.+When [self-hosting](./hosting/self-hosting.md) or using [Plandex Cloud](./hosting/cloud.md) in BYO API Key Mode, API keys are only stored ephemerally in RAM while they are in active use. They are never written to disk, logged, or stored in a database. As soon as a plan stream ends, the API key is removed from memory and no longer exists anywhere on the Plandex server.-It's also up to you to manage your API keys securely. Try to avoid storing them in multiple places, exposing them to third party services, or sending them around in plain text.\ No newline at end of file+It's also up to you to manage your API keys securely. Try to avoid storing them in multiple places, exposing them to third party services, or sending them around in plain text.++You may also want to consider using Plandex Cloud in [Integrated Models Mode](./hosting/cloud.md#integrated-models-mode), which lets you skip dealing with API keys at all.\ No newline at end of file