Skip to content

Open source AI coding agent. Designed for large projects and real world tasks.

lots of work on docs, a bit on README

Dane Schneider2801e7a8df9c
diff --git a/README.md b/README.md
index f3a514d3..4a078a6d 100644
--- a/README.md
+++ b/README.md
@@ -62,12 +62,15 @@
<br>
<h1 align="center" >
- Open source AI coding agent.<br/>
- For large tasks and real world projects.
+ An open source AI coding agent.<br/><br/>
+ <h2 align="center">
+ Designed for large tasks and real world projects.<br/><br/>
+ </h2><br/>
</h1>
-</small>
-💻  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.
+💻  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. It can handle up to 2M tokens of context directly, and can index directories 10x that size or larger with project maps generated by tree-sitter (30+ languages supported).
+
+🔬  **A cumulative diff review sandbox** keeps AI-generated changes separate from your project files until they are ready to go. Command execution is controlled so you can easily roll back and debug. Experience the power of AI without breaking things or leaving behind a mess.
🧠  Combine the best models from Anthropic, OpenAI, Google, and open source providers to build entire features and apps with a robust terminal-based workflow.
@@ -76,26 +79,28 @@
💪  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.
+
+- 🐘 **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).
+
+- 🚦 **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.
+
+- 💬 **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.
+- 🧑‍💻 **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/> -->
@@ -136,7 +141,7 @@
<p>Churn through your backlog, work with unfamiliar technologies, get unstuck, and <strong>spend less time on the boring stuff.</strong></p>
<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, fix bugs, and automatically debug failing commands (like tests, typecheckers, linters, etc.). </p>
<br/> -->
@@ -155,14 +160,13 @@ curl -sL https://plandex.ai/install.sh | bash
[More installation options.](https://docs.plandex.ai/install)
-
## 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 |
+| ------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **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. |
## Provider keys  🔑
@@ -201,9 +205,9 @@ or for short:
pdx
```
-☁️ *If you're using Plandex Cloud, you'll be prompted at this point to start a trial.*
+☁️ _If you're using Plandex Cloud, you'll be prompted at this point to start a trial._
-Then just give a quick the REPL help text a quick read, and you're ready go. The REPL starts in *chat mode* by default, which is good for fleshing out ideas before moving to implementation. Once the task is clear, Plandex will prompt you to switch to *tell mode* to make a detailed plan and start writing code.
+Then just give a quick the REPL help text a quick read, and you're ready go. The REPL starts in _chat mode_ by default, which is good for fleshing out ideas before moving to implementation. Once the task is clear, Plandex will prompt you to switch to _tell mode_ to make a detailed plan and start writing code.
<br/>
@@ -221,7 +225,7 @@ 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 and subscribe
- [Follow @PlandexAI](https://x.com/PlandexAI)
- [Follow @Danenania](https://x.com/Danenania) (Plandex's creator)
@@ -234,5 +238,3 @@ Please feel free to give your feedback, ask questions, report a bug, or just han
⭐️  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)
-
-
diff --git a/app/cli/api/methods.go b/app/cli/api/methods.go
index a6bf4338..9ce5dd05 100644
--- a/app/cli/api/methods.go
+++ b/app/cli/api/methods.go
@@ -2256,7 +2256,7 @@ func (a *Api) GetFileMap(req shared.GetFileMapRequest) (*shared.GetFileMapRespon
return nil, &shared.ApiError{Type: shared.ApiErrorTypeOther, Msg: fmt.Sprintf("error marshalling request: %v", err)}
}
- resp, err := authenticatedFastClient.Post(serverUrl, "application/json", bytes.NewBuffer(reqBytes))
+ resp, err := authenticatedSlowClient.Post(serverUrl, "application/json", bytes.NewBuffer(reqBytes))
if err != nil {
return nil, &shared.ApiError{Type: shared.ApiErrorTypeOther, Msg: fmt.Sprintf("error sending request: %v", err)}
}
diff --git a/app/cli/cmd/delete_branch.go b/app/cli/cmd/delete_branch.go
index 08de12e0..4ef9a919 100644
--- a/app/cli/cmd/delete_branch.go
+++ b/app/cli/cmd/delete_branch.go
@@ -15,7 +15,7 @@ import (
var deleteBranchCmd = &cobra.Command{
Use: "delete-branch",
- Aliases: []string{"db"},
+ Aliases: []string{"dlb"},
Short: "Delete a plan branch by name or index",
Run: deleteBranch,
Args: cobra.MaximumNArgs(1),
diff --git a/app/cli/cmd/delete_plan.go b/app/cli/cmd/delete_plan.go
index ee0dc796..f4997b7f 100644
--- a/app/cli/cmd/delete_plan.go
+++ b/app/cli/cmd/delete_plan.go
@@ -28,7 +28,7 @@ func init() {
var rmCmd = &cobra.Command{
Use: "delete-plan [name-or-index]",
Aliases: []string{"dp"},
- Short: "Delete a plan by name or index, or delete all plans with --all flag",
+ Short: "Delete a plan by name, index, range, or pattern, or select from a list. Delete all plans with --all flag.",
Args: cobra.RangeArgs(0, 1),
Run: del,
}
diff --git a/app/cli/term/help.go b/app/cli/term/help.go
index 5168b9d5..cc5cf28d 100644
--- a/app/cli/term/help.go
+++ b/app/cli/term/help.go
@@ -19,16 +19,16 @@ type CmdConfig struct {
var CliCommands = []CmdConfig{
{"", "", "start the Plandex REPL", false},
- {"--full", "", fmt.Sprintf("start the Plandex REPL with auto-mode %s", color.New(color.Bold).Sprint("full")), false},
- {"--semi", "", fmt.Sprintf("start the Plandex REPL with auto-mode %s", color.New(color.Bold).Sprint("semi")), false},
- {"--plus", "", fmt.Sprintf("start the Plandex REPL with auto-mode %s", color.New(color.Bold).Sprint("plus")), false},
- {"--basic", "", fmt.Sprintf("start the Plandex REPL with auto-mode %s", color.New(color.Bold).Sprint("basic")), false},
- {"--none", "", fmt.Sprintf("start the Plandex REPL with auto-mode %s", color.New(color.Bold).Sprint("none")), false},
+ // {"--full", "", fmt.Sprintf("start the Plandex REPL with auto-mode %s", color.New(color.Bold).Sprint("full")), false},
+ // {"--semi", "", fmt.Sprintf("start the Plandex REPL with auto-mode %s", color.New(color.Bold).Sprint("semi")), false},
+ // {"--plus", "", fmt.Sprintf("start the Plandex REPL with auto-mode %s", color.New(color.Bold).Sprint("plus")), false},
+ // {"--basic", "", fmt.Sprintf("start the Plandex REPL with auto-mode %s", color.New(color.Bold).Sprint("basic")), false},
+ // {"--none", "", fmt.Sprintf("start the Plandex REPL with auto-mode %s", color.New(color.Bold).Sprint("none")), false},
- {"--daily", "", fmt.Sprintf("start the Plandex REPL with %s model pack", color.New(color.Bold).Sprint("daily-driver")), false},
- {"--strong", "", fmt.Sprintf("start the Plandex REPL with %s model pack", color.New(color.Bold).Sprint("strong")), false},
- {"--cheap", "", fmt.Sprintf("start the Plandex REPL with %s model pack", color.New(color.Bold).Sprint("cheap")), false},
- {"--oss", "", fmt.Sprintf("start the Plandex REPL with %s model pack", color.New(color.Bold).Sprint("oss")), false},
+ // {"--daily", "", fmt.Sprintf("start the Plandex REPL with %s model pack", color.New(color.Bold).Sprint("daily-driver")), false},
+ // {"--strong", "", fmt.Sprintf("start the Plandex REPL with %s model pack", color.New(color.Bold).Sprint("strong")), false},
+ // {"--cheap", "", fmt.Sprintf("start the Plandex REPL with %s model pack", color.New(color.Bold).Sprint("cheap")), false},
+ // {"--oss", "", fmt.Sprintf("start the Plandex REPL with %s model pack", color.New(color.Bold).Sprint("oss")), false},
{"new", "", "start a new plan", true},
@@ -95,7 +95,7 @@ var CliCommands = []CmdConfig{
{"branches", "br", "list plan branches", true},
{"checkout", "co", "checkout or create a branch", true},
- {"delete-branch", "db", "delete a branch by name or index", true},
+ {"delete-branch", "dlb", "delete a branch by name or index", true},
{"plans --archived", "", "list archived plans", true},
{"archive", "arc", "archive a plan", true},
@@ -276,7 +276,7 @@ func PrintHelpAllCommands() {
fmt.Fprintln(builder)
color.New(color.Bold, color.BgCyan, color.FgHiWhite).Fprintln(builder, " Changes ")
- printCmds(builder, " ", []color.Attribute{color.Bold, ColorHiCyan}, "diff", "diff --ui", "diff --plain", "changes", "apply", "reject")
+ printCmds(builder, " ", []color.Attribute{color.Bold, ColorHiCyan}, "diff", "diff --ui", "diff --plain", "apply", "reject")
fmt.Fprintln(builder)
color.New(color.Bold, color.BgCyan, color.FgHiWhite).Fprintln(builder, " Context ")
diff --git a/docs/docs/cli-reference.md b/docs/docs/cli-reference.md
index 65f5922d..43b7ec5a 100644
--- a/docs/docs/cli-reference.md
+++ b/docs/docs/cli-reference.md
@@ -50,18 +50,18 @@ pdx
The REPL has a few convenient flags you can use to start it with different modes, autonomy settings, and model packs. You can pass any of these to `plandex` or `pdx` when starting the REPL.
```
- Mode
+ Mode
--chat, -c Start in chat mode (for conversation without making changes)
--tell, -t Start in tell mode (for implementation)
- Autonomy
+ Autonomy
--no-auto None → step-by-step, no automation
--basic Basic → auto-continue plans, no other automation
--plus Plus → auto-update context, smart context, auto-commit changes
--semi Semi-Auto → auto-load context
--full Full-Auto → auto-apply, auto-exec, auto-debug
- Models
+ Models
--daily Daily driver pack (default models, balanced capability, cost, and speed)
--strong Strong pack (more capable models, higher cost and slower)
--cheap Cheap pack (less capable models, lower cost and faster)
@@ -83,7 +83,25 @@ plandex new -n new-plan # with name
`--name/-n`: Name of the new plan. The name is generated automatically after first prompt if no name is specified on creation.
-`--context-dir/-d`: Base directory to load context from when auto-loading context is enabled.
+`--context-dir/-d`: Base directory to load context from when auto-loading context is enabled. Defaults to `.` (current directory). Set a different directoy if you don't want all files to be included in the project map.
+
+`--no-auto`: Start the plan with auto-mode 'None' (step-by-step, no automation).
+
+`--basic`: Start the plan with auto-mode 'Basic' (auto-continue plans, no other automation).
+
+`--plus`: Start the plan with auto-mode 'Plus' (auto-update context, smart context, auto-commit changes).
+
+`--semi`: Start the plan with auto-mode 'Semi-Auto' (auto-load context).
+
+`--full`: Start the plan with auto-mode 'Full-Auto' (auto-apply, auto-exec, auto-debug).
+
+`--daily`: Start the plan with the daily driver model pack.
+
+`--strong`: Start the plan with the strong model pack.
+
+`--cheap`: Start the plan with the cheap model pack.
+
+`--oss`: Start the plan with the open source model pack.
### plans
@@ -125,19 +143,19 @@ With one argument, Plandex selects a plan by name or by index in the `plandex pl
### delete-plan
-Delete a plan by name or index.
+Delete a plan by name, index, range, pattern, or select from a list.
```bash
plandex delete-plan # select from a list of plans
plandex delete-plan some-plan # by name
plandex delete-plan 4 # by index in `plandex plans`
-
+plandex delete-plan 2-4 # by range of indices
+plandex delete-plan 'docs-*' # by pattern
+plandex delete-plan --all # delete all plans
pdx dp # alias
```
-With no arguments, Plandex prompts you with a list of plans to select from.
-
-With one argument, Plandex deletes a plan by name or by index in the `plandex plans` list.
+`--all/-a`: Delete all plans.
### rename
@@ -148,10 +166,6 @@ plandex rename # prompt for new name
plandex rename new-name # set new name
```
-With no arguments, Plandex prompts you for a new name.
-
-With one argument, Plandex sets the new name.
-
### archive
Archive a plan.
@@ -164,10 +178,6 @@ plandex archive 4 # by index in `plandex plans`
pdx arc # alias
```
-With no arguments, Plandex prompts you with a list of plans to select from.
-
-With one argument, Plandex archives a plan by name or by index in the `plandex plans` list.
-
### unarchive
Unarchive a plan.
@@ -203,6 +213,8 @@ pdx l component.ts # alias
`--tree`: Load directory tree layout with file names only.
+`--map`: Load file map of the given directory (function/method/class signatures, variable names, types, etc.)
+
`--note/-n`: Load a note into context.
`--force/-f`: Load files even when ignored by .gitignore or .plandexignore.
@@ -227,12 +239,21 @@ Remove context by index, range, name, or glob.
plandex rm some-file.ts # by name
plandex rm app/**/*.ts # by glob pattern
plandex rm 4 # by index in `plandex ls`
-plandx rm 2-4 # by range of indices
+plandex rm 2-4 # by range of indices
plandex remove # longer alias
plandex unload # longer alias
```
+### show
+
+Output context by name or index.
+
+```bash
+plandex show some-file.ts # by name
+plandex show 4 # by index in `plandex ls`
+```
+
### update
Update any outdated context.
@@ -266,17 +287,29 @@ pdx t # alias
`--file/-f`: File path containing prompt.
-`--stop/-s`: Stop after a single model response (don't auto-continue).
+`--stop/-s`: Stop after a single model response (don't auto-continue). Defaults to opposite of config value `auto-continue`.
-`--no-build/-n`: Don't build proposed changes into pending file updates.
+`--no-build/-n`: Don't build proposed changes into pending file updates. Defaults to opposite of config value `auto-build`.
`--bg`: Run task in the background.
-`--yes/-y`: Automatically confirm context updates.
+`--auto-update-context`: Automatically confirm context updates. Defaults to config value `auto-update-context`.
+
+`--auto-load-context`: Automatically load context using project map. Defaults to config value `auto-load-context`.
+
+`--smart-context`: Use smart context to only load the necessary file(s) for each step during implementation. Defaults to config value `smart-context`.
-`--apply/-a`: Automatically apply changes (and confirm context updates).
+`--no-exec`: Don't execute commands after successful apply. Defaults to opposite of config value `can-exec`.
-`--commit/-c`: Commit changes to git when `--apply/-a` is passed.
+`--auto-exec`: Automatically execute commands after successful apply without confirmation. Defaults to config value `auto-exec`.
+
+`--debug`: Automatically execute and debug failing commands (optionally specify number of tries—default is 5). Defaults to config values of `auto-debug` and `auto-debug-tries`.
+
+`--apply/-a`: Automatically apply changes (and confirm context updates). Defaults to config value `auto-apply`.
+
+`--commit/-c`: Commit changes to git when `--apply/-a` is passed. Defaults to config value `auto-commit`.
+
+`--skip-commit`: Don't commit changes to git. Defaults to opposite of config value `auto-commit`.
### continue
@@ -288,17 +321,29 @@ plandex continue
pdx c # alias
```
-`--stop/-s`: Stop after a single model response (don't auto-continue).
+`--stop/-s`: Stop after a single model response (don't auto-continue). Defaults to opposite of config value `auto-continue`.
-`--no-build/-n`: Don't build proposed changes into pending file updates.
+`--no-build/-n`: Don't build proposed changes into pending file updates. Defaults to opposite of config value `auto-build`.
`--bg`: Run task in the background.
-`--yes/-y`: Automatically confirm context updates.
+`--auto-update-context`: Automatically confirm context updates. Defaults to config value `auto-update-context`.
+
+`--auto-load-context`: Automatically load context using project map. Defaults to config value `auto-load-context`.
+
+`--smart-context`: Use smart context to only load the necessary file(s) for each step during implementation. Defaults to config value `smart-context`.
-`--apply/-a`: Automatically apply changes (and confirm context updates).
+`--no-exec`: Don't execute commands after successful apply. Defaults to opposite of config value `can-exec`.
-`--commit/-c`: Commit changes to git when `--apply/-a` is passed.
+`--auto-exec`: Automatically execute commands after successful apply without confirmation. Defaults to config value `auto-exec`.
+
+`--debug`: Automatically execute and debug failing commands (optionally specify number of tries—default is 5). Defaults to config values of `auto-debug` and `auto-debug-tries`.
+
+`--apply/-a`: Automatically apply changes (and confirm context updates). Defaults to config value `auto-apply`.
+
+`--commit/-c`: Commit changes to git when `--apply/-a` is passed. Defaults to config value `auto-commit`.
+
+`--skip-commit`: Don't commit changes to git. Defaults to opposite of config value `auto-commit`.
### build
@@ -311,11 +356,25 @@ pdx b # alias
`--bg`: Build in the background.
-`--yes/-y`: Automatically confirm context updates.
+`--stop/-s`: Stop after a single model response (don't auto-continue). Defaults to opposite of config value `auto-continue`.
+
+`--no-build/-n`: Don't build proposed changes into pending file updates. Defaults to opposite of config value `auto-build`.
+
+`--bg`: Run task in the background.
+
+`--auto-update-context`: Automatically confirm context updates. Defaults to config value `auto-update-context`.
+
+`--no-exec`: Don't execute commands after successful apply. Defaults to opposite of config value `can-exec`.
+
+`--auto-exec`: Automatically execute commands after successful apply without confirmation. Defaults to config value `auto-exec`.
+
+`--debug`: Automatically execute and debug failing commands (optionally specify number of tries—default is 5). Defaults to config values of `auto-debug` and `auto-debug-tries`.
+
+`--apply/-a`: Automatically apply changes (and confirm context updates). Defaults to config value `auto-apply`.
-`--apply/-a`: Automatically apply changes (and confirm context updates).
+`--commit/-c`: Commit changes to git when `--apply/-a` is passed. Defaults to config value `auto-commit`.
-`--commit/-c`: Commit changes to git when `--apply/-a` is passed.
+`--skip-commit`: Don't commit changes to git. Defaults to opposite of config value `auto-commit`.
### chat
@@ -323,16 +382,20 @@ 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?"
-pdx ct # alias
+pdx ch # alias
```
`--file/-f`: File path containing prompt.
-`--yes/-y`: Automatically confirm context updates.
+`--bg`: Run task in the background.
+
+`--auto-update-context`: Automatically confirm context updates. Defaults to config value `auto-update-context`.
+
+`--auto-load-context`: Automatically load context using project map. Defaults to config value `auto-load-context`.
### debug
-Repeatedly run a command and auto-apply fixes until it succeeds. Defaults to 5 tries before giving up.
+Repeatedly run a command and automatically attempt fixes until it succeeds, rolling back changes on failure. Defaults to 5 tries before giving up.
```bash
plandex debug 'npm test' # try 5 times or until it succeeds
@@ -340,7 +403,9 @@ 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.
+`--commit/-c`: Commit changes to git when `--apply/-a` is passed. Defaults to config value `auto-commit`.
+
+`--skip-commit`: Don't commit changes to git. Defaults to opposite of config value `auto-commit`.
## Changes
@@ -357,15 +422,9 @@ plandex diff --ui
`--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.
-
-### changes
-
-Review pending changes in a TUI.
+`--side-by-side/-s`: Show diffs UI in side-by-side view
-```bash
-plandex changes
-```
+`--line-by-line/-l`: Show diffs UI in line-by-line view
### apply
@@ -376,17 +435,26 @@ plandex apply
pdx ap # alias
```
-`--yes/-y`: Skip confirmation.
+`--bg`: Run task in the background.
+
+`--auto-update-context`: Automatically confirm context updates. Defaults to config value `auto-update-context`.
+
+`--no-exec`: Don't execute commands after successful apply. Defaults to opposite of config value `can-exec`.
+
+`--auto-exec`: Automatically execute commands after successful apply without confirmation. Defaults to config value `auto-exec`.
+
+`--debug`: Automatically execute and debug failing commands (optionally specify number of tries—default is 5). Defaults to config values of `auto-debug` and `auto-debug-tries`.
-`--commit/-c`: Commit changes to git.
+`--commit/-c`: Commit changes to git when `--apply/-a` is passed. Defaults to config value `auto-commit`.
-`--skip-commit`: Don't commit changes to git.
+`--skip-commit`: Don't commit changes to git. Defaults to opposite of config value `auto-commit`.
### reject
Reject pending changes to one or more project files.
```bash
+plandex reject # select from a list of pending files to reject
plandex reject file.ts # one file
plandex reject file.ts another-file.ts # multiple files
plandex reject --all # all pending files
@@ -414,15 +482,11 @@ plandex logs # alias
Rewind to a previous state.
```bash
-plandex rewind # rewind 1 step
+plandex rewind # select from a list of previous states to rewind to
plandex rewind 3 # rewind 3 steps
plandex rewind a7c8d66 # rewind to a specific step from `plandex log`
```
-With no arguments, Plandex rewinds one step.
-
-With one argument, Plandex rewinds the specified number of steps (if an integer is passed) or rewinds to the specified step (if a hash from `plandex log` is passed).
-
### convo
Show the current plan's conversation.
@@ -477,13 +541,9 @@ plandex delete-branch # select from a list of branches
plandex delete-branch some-branch # by name
plandex delete-branch 4 # by index in `plandex branches`
-pdx db # alias
+pdx dlb # alias
```
-With no arguments, Plandex prompts you with a list of branches to select from.
-
-With one argument, Plandex deletes a branch by name or by index in the `plandex branches` list.
-
## Background Tasks / Streams
### ps
@@ -502,14 +562,9 @@ Connect to an active plan stream.
plandex connect # select from a list of active streams
plandex connect a4de # by stream ID in `plandex ps`
plandex connect some-plan main # by plan name and branch name
+pdx conn # alias
```
-With no arguments, Plandex prompts you with a list of active streams to select from.
-
-With one argument, Plandex connects to a stream by stream ID in the `plandex ps` list.
-
-With two arguments, Plandex connects to a stream by plan name and branch name.
-
### stop
Stop an active plan stream.
@@ -520,11 +575,75 @@ plandex stop a4de # by stream ID in `plandex ps`
plandex stop some-plan main # by plan name and branch name
```
-With no arguments, Plandex prompts you with a list of active streams to select from.
+## Configuration
+
+### config
+
+Show current plan config. Output includes configuration settings for the plan, such as autonomy level, model settings, and other plan-specific options.
+
+```bash
+plandex config
+```
+
+### config default
+
+Show the default config used for new plans. Output includes the default configuration settings that will be applied to newly created plans.
+
+```bash
+plandex config default
+```
-With one argument, Plandex connects to a stream by stream ID in the `plandex ps` list.
+### set-config
-With two arguments, Plandex connects to a stream by plan name and branch name.
+Update configuration settings for the current plan.
+
+```bash
+plandex set-config # select from a list of config options
+plandex set-config auto-context true # set a specific config option
+```
+
+With no arguments, Plandex prompts you to select from a list of config options.
+
+With arguments, allows you to directly set specific configuration options for the current plan.
+
+### set-config default
+
+Update the default configuration settings for new plans.
+
+```bash
+plandex set-config default # select from a list of config options
+plandex set-config default auto-mode basic # set a specific default config option
+```
+
+Works exactly the same as set-config above, but sets the default configuration for all new plans instead of only the current plan.
+
+### set-auto
+
+Update the auto-mode (autonomy level) for the current plan.
+
+```bash
+plandex set-auto # select from a list of auto-modes
+plandex set-auto full # set to full automation
+plandex set-auto semi # set to semi-auto mode
+plandex set-auto plus # set to plus mode
+plandex set-auto basic # set to basic mode
+plandex set-auto none # set to none (step-by-step, no automation)
+```
+
+With no arguments, Plandex prompts you to select from a list of automation levels.
+
+With one argument, Plandex sets the automation level directly to the specified value.
+
+### set-auto default
+
+Set the default auto-mode for new plans.
+
+```bash
+plandex set-auto default # select from a list of auto-modes
+plandex set-auto default basic # set default to basic mode
+```
+
+Works exactly the same as set-auto above, but sets the default automation level for all new plans instead of only the current plan.
## Models
@@ -632,6 +751,8 @@ Show all available model packs.
plandex model-packs
```
+`--custom`: Show available custom (user-created) model packs only.
+
### model-packs create
Create a new custom model pack.
@@ -672,7 +793,7 @@ Invite a user to join your org.
```bash
plandex invite # prompt for email, name, and role
-plandex invite [email protected] 'Full Name' member # invite with email, name, and role
+plandex invite [email protected] 'Full Name' member # invite with email, name, and role
```
Users can be invited as `member`, `admin`, or `owner`.
diff --git a/docs/docs/core-concepts/autonomy.md b/docs/docs/core-concepts/autonomy.md
new file mode 100644
index 00000000..cbde61b4
--- /dev/null
+++ b/docs/docs/core-concepts/autonomy.md
@@ -0,0 +1,4 @@
+---
+sidebar_position: 2
+sidebar_label: Autonomy
+---
diff --git a/docs/docs/core-concepts/background-tasks.md b/docs/docs/core-concepts/background-tasks.md
index d20557bf..869a2ede 100644
--- a/docs/docs/core-concepts/background-tasks.md
+++ b/docs/docs/core-concepts/background-tasks.md
@@ -1,5 +1,5 @@
---
-sidebar_position: 8
+sidebar_position: 11
sidebar_label: Background Tasks
---
diff --git a/docs/docs/core-concepts/branches.md b/docs/docs/core-concepts/branches.md
index 3d45a631..fc56123b 100644
--- a/docs/docs/core-concepts/branches.md
+++ b/docs/docs/core-concepts/branches.md
@@ -1,5 +1,5 @@
---
-sidebar_position: 6
+sidebar_position: 8
sidebar_label: Branches
---
@@ -18,6 +18,7 @@ To create a new branch, use the `plandex checkout` command:
```bash
plandex checkout new-branch
+pdxd new-branch # alias
```
## Switching Branches
diff --git a/docs/docs/core-concepts/configuration.md b/docs/docs/core-concepts/configuration.md
new file mode 100644
index 00000000..c2b044a1
--- /dev/null
+++ b/docs/docs/core-concepts/configuration.md
@@ -0,0 +1,6 @@
+---
+sidebar_position: 10
+sidebar_label: Configuration
+---
+
+# Configuration
diff --git a/docs/docs/core-concepts/context-management.md b/docs/docs/core-concepts/context-management.md
index bedfaea1..31c86fae 100644
--- a/docs/docs/core-concepts/context-management.md
+++ b/docs/docs/core-concepts/context-management.md
@@ -1,5 +1,5 @@
---
-sidebar_position: 2
+sidebar_position: 3
sidebar_label: Context
---
@@ -9,7 +9,103 @@ Context in Plandex refers to files, directories, URLs, images, notes, or piped i
Changes to context are [version controlled](./version-control.md) and can be [branched](./branches.md).
-## Loading Context
+## Automatic vs. Manual
+
+As of 2.0.0, Plandex loads context automatically by default. When a new plan is created, a [project map](#loading-project-maps) is generated and loaded into context. The LLM then uses this map to select relevant context before planning a task or responding to a message.
+
+### Tradeoffs
+
+Automatic context loading makes Plandex more powerful and easier to work with, but there are tradeoffs in terms of cost, focus, and output speed. If you're trying to minimize costs or you know for sure that only one or two files are relevant to a task, you might prefer to load context manually.
+
+### Setting Manual Mode
+
+You can use manual context loading by:
+
+- Setting the `auto-load-context` config option to `false`:
+
+```bash
+plandex set-config auto-load-context false
+plandex set-config default auto-load-context false # set the default value for all new plans
+```
+
+- Using `set-auto` to choose a lower [autonomy level](./autonomy.md) that has auto-load-context disabled (like `plus` or `basic`).
+
+```bash
+plandex set-auto plus
+plandex set-auto basic
+plandex set-auto default plus # set the default value for all new plans
+```
+
+- Starting a new REPL or a new plan with the `--plus` or `--basic` flags, which will automatically set the config option to the chosen autonomy level.
+
+```bash
+plandex --plus
+plandex new --basic
+```
+
+### Smart Context Window Management
+
+Another new context management feature in 2.0.0 is smart context window management. When making a plan with multiple steps, Plandex will determine which files are relevant to each step. Only those files will be loaded into context during implementation.
+
+When combined with automatic context loading, this effectively creates a sliding context window that grows and shrinks as needed throughout the plan.
+
+Smart context can also be used when you're managing context manually. To give an example: say you've manually loaded a directory with 10 files in it, and you need to make some updates to each one of them. Without smart context, each step of the implementation will load all 10 files into context. But if you use smart context, only the one or two files that are edited in each step will be loaded.
+
+Smart context is enabled in the `plus` autonomy level and above. You can also toggle it with `set-config`:
+
+```bash
+plandex set-config smart-context true
+plandex set-config smart-context false
+plandex set-config default smart-context false # set the default value for all new plans
+```
+
+### Automatic Context Updates
+
+When you make your own changes to files in context separately from Plandex, those files need to be updated before the plan can continue. Previously, Plandex would prompt you to update context every time a file was changed. This is now automatic by default.
+
+Automatic updates are enabled in the `plus` autonomy level and above. You can also toggle them with `set-config`:
+
+```bash
+plandex set-config auto-update-context true
+plandex set-config auto-update-context false
+plandex set-config default auto-update-context false # set the default value for all new plans
+```
+
+### Context-Autonomy Matrix
+
+Here are the different autonomy levels as they relate to context management config options:
+
+| | `none` | `basic` | `plus` | `semi` | `full` |
+| --------------------- | ------ | ------- | ------ | ------ | ------ |
+| `auto-load-context` | ❌ | ❌ | ✅ | ✅ | ✅ |
+| `smart-context` | ❌ | ❌ | ✅ | ✅ | ✅ |
+| `auto-update-context` | ❌ | ❌ | ✅ | ✅ | ✅ |
+
+### Mixing Automatic and Manual Context
+
+You can manually load additional context even if automatic loading is enabled. The way this additional context is handled works somewhat differently.
+
+First, consider how automatic context loading works across each stage of a plan:
+
+#### Automatic context loading (no manual context added)
+
+1. **Context loading:** Only the project map is initially loaded. The map, along with your prompt, is used to select relevant context.
+2. **Planning:** Only context selected in step 1 is loaded.
+3. **Implementation:** Smart context (if enabled) filters context again, loading only what's directly relevant to each step.
+
+Here's how it changes when you load manual context on top:
+
+#### Automatic loading + manual context
+
+1. **Context loading:** Your manually loaded context is **always included** alongside the project map.
+2. **Planning:** Manually loaded context is always loaded, whether or not it's selected by the map-based context selection step.
+3. **Implementation:** Smart context (if enabled) filters all context again (both manual and automatic), loading only what's directly relevant to each implementation step.
+
+Loading files manually when using automatic context loading can sometimes be useful when you **know** certain files are relevant and don't want to risk the LLM leaving them out, or when the LLM is struggling to select the right context. If there are files that can help the LLM select the right context, like READMEs or documentation that describes the structure of the project, those can also be good candidates for manual loading.
+
+Another use for manual context loading is for context types that can't be loaded automatically, like images, URLs, notes, or piped data (for now Plandex can only automatically load project files).
+
+## Manually Loading Context
To load files, directories, directory layouts, urls, images, notes, or piped data into a plan's context, use the `plandex load` command.
@@ -20,6 +116,7 @@ You can pass `load` one or more file paths. File paths are relative to the curre
```bash
plandex load component.ts # single file
plandex load component.ts action.ts reducer.ts # multiple files
+pdx l component.ts # alias
```
You can also load multiple files using glob patterns:
@@ -45,6 +142,15 @@ plandex load lib -r # loads lib, all its files and all its subdirectories
plandex load * -r # loads all files in the current directory and all its subdirectories
```
+### Loading Files and Directories in the REPL
+
+In the [Plandex REPL](./repl.md), you can use the shortcut `@` plus a relative file path to load a file or directory into context.
+
+```bash
[email protected] # loads component.ts
+@lib # loads lib directory, and all its files and subdirectories
+```
+
### Loading Directory Layouts
There are tasks where it's helpful for the LLM to the know the structure of your project or sections of your project, but it doesn't necessarily need to the see the content of every file. In that case, you can pass in a directory with the `--tree` flag to load in the directory layout. It will include just the names of all included files and subdirectories (and each subdirectory's files and subdirectories, and so on).
@@ -54,6 +160,16 @@ plandex load . --tree # loads the layout of the current directory and its subdir
plandex load src/components --tree # loads the layout of the src/components directory
```
+### Loading Project Maps
+
+Plandex can create a **project map** for any directory using [tree-sitter](https://tree-sitter.github.io/tree-sitter). This shows all the top-level symbols, like variables, functions, classes, etc. in each file. 30+ languages are supported. For non-supported languages, files are still listed without symbols so that the model is aware of their existence.
+
+Maps are mainly used for selecting context during automatic context loading, but can also be used with manual context management in order to improve output. Maps make it much more likely that an LLM will, for example, use an existing function in your project (and call it correctly) rather than generating a new one that does the same thing.
+
+```bash
+plandex load . --map
+```
+
### Loading URLs
Plandex can load the text content of URLs, which can be useful for adding relevant documentation, blog posts, discussions, and the like.
@@ -108,6 +224,13 @@ To list everything in context, use the `plandex ls` command:
plandex ls
```
+You can also see the content of any context item with the `plandex show` command:
+
+```bash
+plandex show component.ts # show the content of component.ts
+plandex show 2 # show the content of the second item in the `plandex ls` list
+```
+
## Removing Context
To remove selectively remove context, use the `plandex rm` command:
@@ -130,8 +253,12 @@ plandex clear
## Updating Context
-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.
+If files, directory layouts, or URLs in context are modified outside of Plandex, they will need to be updated next time you send a prompt.
+
+Whether they'll be updated automatically or you'll be prompted to update them depends on the `auto-update-context` config option.
+
+You can also update any outdated files with the `update` command.
```bash
plandex update # update files in context
-```
\ No newline at end of file
+```
diff --git a/docs/docs/core-concepts/conversations.md b/docs/docs/core-concepts/conversations.md
index 6688fafc..79bbeeb8 100644
--- a/docs/docs/core-concepts/conversations.md
+++ b/docs/docs/core-concepts/conversations.md
@@ -1,5 +1,5 @@
---
-sidebar_position: 7
+sidebar_position: 9
sidebar_label: Conversations
---
@@ -46,4 +46,3 @@ As with the `convo` command, you can output the summary in plain text with no AN
```bash
plandex summary --plain
```
-
diff --git a/docs/docs/core-concepts/debugging-commands.md b/docs/docs/core-concepts/execution-and-debugging.md
similarity index 84%
rename from docs/docs/core-concepts/debugging-commands.md
rename to docs/docs/core-concepts/execution-and-debugging.md
index b87f8619..3b87837f 100644
--- a/docs/docs/core-concepts/debugging-commands.md
+++ b/docs/docs/core-concepts/execution-and-debugging.md
@@ -1,11 +1,13 @@
---
-sidebar_position: 9
-sidebar_label: Debug Terminal Commands
+sidebar_position: 6
+sidebar_label: Execution and Debugging
---
-# Debug Terminal Commands
+# Execution and Debugging
-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.
+As of version 2.0.0, Plandex includes powerful new execution and automated debugging capabilities.
+
+`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`
@@ -44,7 +46,7 @@ plandex debug "echo 'ok'" # succeeds and immediately exits
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.
+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`
diff --git a/docs/docs/core-concepts/orgs.md b/docs/docs/core-concepts/orgs.md
index 3c634df2..21412f54 100644
--- a/docs/docs/core-concepts/orgs.md
+++ b/docs/docs/core-concepts/orgs.md
@@ -1,5 +1,5 @@
---
-sidebar_position: 10
+sidebar_position: 12
sidebar_label: Collaboration / Orgs
---
@@ -45,4 +45,4 @@ To revoke an invite or remove a user, use `plandex revoke`:
```bash
plandex revoke
-```
\ No newline at end of file
+```
diff --git a/docs/docs/core-concepts/plans.md b/docs/docs/core-concepts/plans.md
index c6cd575a..31795a3d 100644
--- a/docs/docs/core-concepts/plans.md
+++ b/docs/docs/core-concepts/plans.md
@@ -5,13 +5,13 @@ sidebar_label: Plans
# Plans
-A **plan** in Plandex is similar to a conversation in ChatGPT. It might only include a single prompt and model response that executes one small task, or it could represent a long back and forth with the model that generates dozens of files and builds a whole feature or an entire project.
+A **plan** in Plandex is similar to a conversation in ChatGPT or Claude. It might only include a single prompt and model response that executes one small task, or it could represent a long back and forth with the model that generates dozens of files and builds a whole feature or an entire project.
-A plan includes:
+A plan includes:
-- Any context that you've loaded.
-- Your conversation with the model.
-- Any proposed changes that have been accumulated during the course of the conversation.
+- Any [context](./context-management.md) that you or the model have loaded.
+- Your [conversation](./conversation.md) with the model.
+- Any [pending changes](./reviewing-changes.md) that have been accumulated during the course of the conversation.
Plans support [version control](./version-control.md) and [branches](./branches.md).
@@ -23,7 +23,21 @@ First `cd` into your **project's directory.** Make a new directory first with `m
cd your-project-dir
```
-Then **start your first plan** with `plandex new`.
+### REPL
+
+To start a new plan with the REPL, just run:
+
+```bash
+plandex
+```
+
+If you haven't created a new plan in this directory previously, a plan will automatically be created for you when the REPL starts.
+
+If already have a plan loaded in the REPL (you can check with `\current`), you can start a new plan with `\new`.
+
+### CLI
+
+You can create a new plan through the CLI with `plandex new`.
```bash
plandex new
@@ -91,7 +105,7 @@ plandex unarchive 2 # unarchive a plan by number in the `plandex plans --archive
## .plandex Directory
-When you run `plandex new` for the first time in any directory, Plandex will create a `.plandex` directory there for light project-level config.
+When you run `plandex` (for a REPL) or `plandex new` for the first time in any directory, Plandex will create a `.plandex` directory there for light project-level config.
If multiple people are using Plandex with the same project, you should either:
@@ -100,6 +114,12 @@ If multiple people are using Plandex with the same project, you should either:
## Project Directories
-So far, we've assumed you're running `plandex new` to create plans in your project's root directory. While that is the most common use case, it can be useful to create plans in subdirectories of your project too. That's because context file paths in Plandex are specified relative to the directory where the plan was created. So if you're working on a plan for just one part of your project, you might want to create the plan in a subdirectory in order to shorten paths when loading context or referencing files in your prompts. This can also help with plan organization if you have a lot of plans.
+So far, we've assumed you're running `plandex` or `plandex new` to create plans in your project's root directory. While that is the most common use case, it can be useful to create plans in subdirectories of your project too.
+
+That's because context file paths in Plandex are specified relative to the directory where the plan was created. So if you're working on a plan for just one part of your project, you might want to create the plan in a subdirectory in order to shorten paths when loading context or referencing files in your prompts.
+
+Starting a plan (or REPL) in a subdirectory is also helpful when using [automatic context loading](./context-management.md#automatic-vs-manual) to limit the size of the project map and what files are available for the LLM to load.
+
+It can also help with plan organization if you have a lot of plans.
-When you run `plandex plans`, in addition to showing you plans in the current directory, Plandex will also show you plans in nearby parent directories or subdirectories. This helps you keep track of what plans you're working on and where they are in your project hierarchy. If you want to switch to a plan in a different directory, first `cd` into that directory, then run `plandex cd` to select the plan.
\ No newline at end of file
+When you run `plandex plans`, in addition to showing you plans in the current directory, Plandex will also show you plans in nearby parent directories or subdirectories. This helps you keep track of what plans you're working on and where they are in your project hierarchy. If you want to switch to a plan in a different directory, first `cd` into that directory, then run `plandex cd` to select the plan.
diff --git a/docs/docs/core-concepts/prompts.md b/docs/docs/core-concepts/prompts.md
index de84bcd0..2644d62e 100644
--- a/docs/docs/core-concepts/prompts.md
+++ b/docs/docs/core-concepts/prompts.md
@@ -1,5 +1,5 @@
---
-sidebar_position: 3
+sidebar_position: 4
sidebar_label: Prompts
---
@@ -7,30 +7,48 @@ sidebar_label: Prompts
## Sending Prompts
-To send a prompt, use the `plandex tell` command.
+### In the REPL
+
+To send a prompt in the [REPL](../repl.md), just type your prompt and press enter.
+
+You can also use `\multi` to enable multi-line mode. This will cause enter to produce line breaks. In multi-line mode, you can send your prompt with `\send`.
+
+If you want to pass in a file as a prompt in the REPL, you can use the `\run` command with a relative file path:
+
+```
+\run src/components/foobars-form.tsx
+```
+
+### With the CLI
+
+To send a prompt with the CLI, use the `plandex tell` command for a task, or the `plandex chat` command to brainstorm or ask questions.
You can pass it in as a file with the `--file/-f` flag:
```bash
plandex tell -f prompt.txt
+plandex chat -f prompt.txt
```
Write it in vim:
```bash
plandex tell # tell with no arguments opens vim so you can write your prompt there
+plandex chat # chat with no arguments does the same
```
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 chat "where's the database connection logic in this project?"
```
You can also pipe in the results of another command:
```bash
git diff | plandex tell
+git diff | plandex chat
```
When you pipe in results like this, you can also supply an inline string to give a label or additional context to the results:
@@ -41,7 +59,7 @@ git diff | plandex tell "'git diff' output"
## Plan Stream TUI
-After you send a prompt with `plandex tell`, you'll see the plan stream TUI. The model's responses are streamed here. You'll see several hotkeys listed along the bottom row that allow you to stop the plan (s), send the plan to the background (b), scroll/page the streamed text, or jump to the beginning or end of the stream. If you're a vim user, you'll notice Plandex's scrolling hotkeys are the same as vim's.
+After you send a prompt with the REPL, `plandex tell`, or `plandex chat`, you'll see the plan stream TUI. The model's responses are streamed here. You'll see several hotkeys listed along the bottom row that allow you to stop the plan (s), send the plan to the background (b), scroll/page the streamed text, or jump to the beginning or end of the stream. If you're a vim user, you'll notice Plandex's scrolling hotkeys are the same as vim's.
Note that scrolling the terminal window itself won't work while you're in the stream TUI. Use the scroll hotkeys instead.
@@ -49,7 +67,7 @@ Note that scrolling the terminal window itself won't work while you're in the st
When you give Plandex a task, it will first break down the task into steps, then it will proceed to implement each step in code. Plandex will automatically continue sending model requests until the task is determined to be complete.
-## Conversational Prompts
+## Chat Prompts
If you want to ask Plandex questions or chat without generating files or making changes, use the `plandex chat` command instead of `plandex tell`.
@@ -61,6 +79,10 @@ Plandex will reply with just a single response, won't create or update any files
`plandex chat` has the same options for passing in a prompt as `plandex tell`. You can pass a string inline, give it a file with `--file/-f`, type the prompt in vim by running `plandex chat` with no arguments, or pipe in the results of another command.
+### In the REPL
+
+In the REPL, you can control whether prompts are sent to `plandex tell` or `plandex chat` under the hood by toggling `chat mode` with `\chat (\ch)` or `\tell (\t)`.
+
## Stopping and Continuing
When using `plandex tell`, you can prevent Plandex from automatically continuing for multiple responses by passing the `--stop/-s` flag:
@@ -77,6 +99,20 @@ plandex continue -s
Apart from `--stop/-s` Plandex's plan stream TUI also has an `s` hotkey that allows you to immediately stop a plan.
+You can also stop a plan from automatically continuing by setting the `auto-continue` config option to `false` in a plan's [configuration](./configuration.md):
+
+```bash
+plandex set-config auto-continue false
+plandex set-config default auto-continue false # set the default config's auto-continue to false for all new plans
+```
+
+or by setting the `auto-mode` ([autonomy level](./autonomy.md)) to `none`:
+
+```bash
+plandex set-auto none
+plandex set-default-auto none # set the default auto-mode to none for all new plans
+```
+
## Background Tasks
By default, `plandex tell` opens the plan stream TUI and streams Plandex's response(s) there, but you can also pass the `--bg` flag to run a task in the background instead.
@@ -85,23 +121,37 @@ You can learn more about using and interacting with background tasks [here](./ba
## 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.
+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](./context-management.md) have changed. If so, you'll need to update the context before continuing.
+
+By default, Plandex will update any outdated context automatically, but if you'd rather approve these updates, you can set the `auto-update-context` config option to `false`:
-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 set-config auto-update-context false
+plandex set-config default auto-update-context false # set the default config's auto-update-context to false for all new plans
+```
+
+or you can set the `auto-mode` to `basic` or `none`:
```bash
-plandex tell -y "add a cancel button to the foobars form in src/components/foobars-form.tsx"
+plandex set-auto basic
+plandex set-auto none
```
## Building Files
As 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 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`.
+By default, these changes initially **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)
+### Full auto mode
+
+An important caveat to the above: if you set the `auto-mode` to `full`, Plandex _will_ automatically apply the changes to your project files,
+
### 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 building files.
@@ -139,7 +189,7 @@ plandex tell "now implement the UI portion of the forgot password flow"
## 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`:
+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
diff --git a/docs/docs/core-concepts/reviewing-changes.md b/docs/docs/core-concepts/reviewing-changes.md
index feb4c1b1..88f2ba30 100644
--- a/docs/docs/core-concepts/reviewing-changes.md
+++ b/docs/docs/core-concepts/reviewing-changes.md
@@ -1,5 +1,5 @@
---
-sidebar_position: 4
+sidebar_position: 5
sidebar_label: Pending Changes
---
@@ -7,6 +7,10 @@ sidebar_label: Pending Changes
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.
+## Review Menu
+
+Once Plandex has finished with a task, you'll see a review menu with several hotkey options. These hotkeys act as shortcuts for the commands described below.
+
## `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:
@@ -23,25 +27,24 @@ You can also view them in a local browser UI with the `plandex diffs --ui` comma
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 Files
-While 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.
+If the plan's changes were applied incorrectly to a file, or you don't want to apply them for another reason, 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 or more file paths:
+To reject changes to a file (or multiple files), you can run `plandex reject`. You'll be prompted to select which files to reject.
```bash
-plandex reject some-file.py
+plandex reject # select files to reject
```
-You can reject *all* currently pending files by passing no arguments to the reject command (you'll then be prompted to confirm the rejection):
+You can reject _all_ currently pending files by passing the `--all` flag to the reject command, or you can pass a list of specific files to reject:
```bash
-plandex reject
+plandex reject --all
+plandex reject file1.ts file2.ts
```
-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.
+If you rejected a file due to the changes being applied incorrectly, but you still want to use the code, either scroll up and copy the changes from the plan's output or run `plandex convo` to output the full conversation and copy from there. Then apply the updates to that file yourself.
## Apply The Changes
@@ -63,4 +66,4 @@ You can pass the `--skip-commit` flag to prevent the changes from being committe
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 file
+If you do this, you can also pass the `--commit/-c` flag to commit the automatically applied changes to git.
diff --git a/docs/docs/core-concepts/version-control.md b/docs/docs/core-concepts/version-control.md
index 48ce93bc..43ca7382 100644
--- a/docs/docs/core-concepts/version-control.md
+++ b/docs/docs/core-concepts/version-control.md
@@ -1,5 +1,5 @@
---
-sidebar_position: 5
+sidebar_position: 7
sidebar_label: Version Control
---
@@ -7,7 +7,7 @@ sidebar_label: Version Control
Just about every aspect of a Plandex plan is version-controlled, and anything that can happen during a plan creates a new version in the plan's history. This includes:
-- Adding, removing, or updating context.
+- Adding, removing, or updating context (when you do it manually or when Plandex does it automatically).
- When you send a prompt.
- When Plandex responds.
- When Plandex builds the plan's proposed updates to a file into a pending change.
@@ -28,7 +28,7 @@ plandex log
To rewind the plan to an earlier state, use the `plandex rewind` command:
```bash
-plandex rewind # Rewind 1 step
+plandex rewind # Select a previous state to rewind to
plandex rewind 3 # Rewind 3 steps
plandex rewind a7c8d66 # Rewind to a specific step
```
@@ -40,7 +40,7 @@ Note that currently, there's no way to undo a `rewind` and recover any history t
```bash
plandex checkout undo-changes # create a new branch called 'undo-changes'
plandex rewind ef883a # history is rewound in 'undo-changes' branch
-plandex checkout main # main branch still retains original history
+plandex checkout main # main branch still retains original history
```
## Viewing Conversation
@@ -53,6 +53,13 @@ plandex convo
## Rewinding After `plandex apply`
-Like any other action that modifies a plan, running `plandex apply` to apply pending changes to your project file creates a new version in the plan's history.
+Like any other action that modifies a plan, running `plandex apply` to apply pending changes to your project file creates a new version in the plan's history. The `plandex apply` action can also be undone with `plandex rewind`.
-The `plandex apply` action can be undone with `plandex rewind`, but it's important to note that this will only make the changes pending again in the Plandex sandbox. It **will not** undo the changes to your project files. You'll have to do that separately if desired.
+While previous versions Plandex would not also revert the changes to your project files, this is now the default behavior as of v2.0.0. If there are potential conflicts (i.e. you've made changes on top since applying), Plandex will prompt you to decide how to handle the conflict.
+
+This behavior can be disabled if desired by setting the `auto-revert-on-rewind` config setting to `false`:
+
+```bash
+plandex set-config auto-revert-on-rewind false
+plandex set-config default auto-revert-on-rewind false # set the default value for all new plans
+```
diff --git a/docs/docs/hosting/cloud.md b/docs/docs/hosting/cloud.md
index 466ea0c9..f4b59200 100644
--- a/docs/docs/hosting/cloud.md
+++ b/docs/docs/hosting/cloud.md
@@ -7,19 +7,19 @@ sidebar_label: Cloud
## Overview
-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 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`.
## Billing Modes
Plandex Cloud has two billing modes:
-### Integrated Models
+### Integrated Models
-- Use Plandex credits to pay for AI models.
-- No separate accounts or API keys are required.
+- 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 $10 trial (includes $10 in credits).
-- After the trial, you can upgrade to a paid plan for $40 per month—includes $15 in credits every month that never expire.
+- After the trial, you can upgrade to a paid plan for $45 per month—includes $20 in credits every month that never expire.
### BYO API Key
@@ -55,8 +55,8 @@ Data sent to Plandex Cloud may be shared with the following third parties:
- [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.
- Your name and email are shared with our payment processor [Stripe](https://stripe.com/) if you subscribe to a paid plan or purchase the $10 trial.
-- Usage data is sent to [Google Analytics](https://analytics.google.com/) to help us track usage and make improvements.
+- Basic usage data is sent to [Google Analytics](https://analytics.google.com/) to help 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 if any new third party services are introduced.
-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 file
+Data sent to a model provider like OpenAI or OpenRouter.ai is subject to the model provider's privacy and data retention policies.
diff --git a/docs/docs/install.md b/docs/docs/install.md
index 3cab5072..178157f4 100644
--- a/docs/docs/install.md
+++ b/docs/docs/install.md
@@ -1,5 +1,5 @@
---
-sidebar_position: 2
+sidebar_position: 1
sidebar_label: Install
---
@@ -8,7 +8,7 @@ sidebar_label: Install
## Quick Install
```bash
-curl -sL https://plandex.ai/install.sh | bash
+curl -sL https://v2.plandex.ai/install.sh | bash
```
## Manual install
@@ -19,7 +19,7 @@ Grab the appropriate binary for your platform from the latest [release](https://
```bash
git clone https://github.com/plandex-ai/plandex.git
-git clone https://github.com/plandex-ai/survey.git
+git checkout v2
cd plandex/app/cli
go build -ldflags "-X plandex/version.Version=$(cat version.txt)"
mv plandex /usr/local/bin # adapt as needed for your system
diff --git a/docs/docs/intro.md b/docs/docs/intro.md
deleted file mode 100644
index a539260c..00000000
--- a/docs/docs/intro.md
+++ /dev/null
@@ -1,72 +0,0 @@
----
-title: Intro
-description: Plandex is an open source, terminal-based AI coding engine that helps you work on complex, real-world development tasks with LLMs.
-sidebar_position: 1
-sidebar_label: Intro
----
-
-# Introduction
-
-Plandex is an open source, terminal-based AI coding engine that helps you work on complex, real-world development tasks with LLMs.
-
-It combines multiple agents to complete tasks that span many files and model responses. When you give Plandex a task, it continues working automatically until the task is determined to be complete.
-
-## Use cases
-
-- Build new projects from scratch.
-- Add features to existing projects.
-- Write tests.
-- Write scripts.
-- Fix bugs.
-- Refactor.
-- Work with unfamiliar technologies.
-- Ask questions about code.
-- Understand a codebase.
-- Auto-debug a failing shell command (tests, type checks, scripts, etc.).
-
-## What makes Plandex different?
-
-### Version Control
-
-Plandex gives the LLM its own version-controlled staging area/sandbox (separate from your project's git repo) where all of its proposed changes are accumulated. This allows you to:
-
-- Iterate on your code and the LLM's plan at the same time without the changes becoming intertwined and difficult to disentangle.
-- Review proposed changes across multiple files as a whole (rejecting any that aren't correct) to be sure that broken updates or hallucinations don't make it into your project files.
-- Branch or rewind the LLM's plan in order to explore multiple paths or revert to the exact step where a task went off the rails.
-
-### Context Management
-
-Apart from version control, Plandex also helps you manage what's in the LLM's context:
-
-- Add files or directories to context from the terminal instead of copying and pasting or clicking around in a UI.
-- 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.
-
-### Automated Debugging
-
-Plandex can repeatedly run a failing terminal command, continually making fixes based on the command's output and retrying until it succeeds.
-
-## Models
-
-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 from any OpenAI-compatible provider.
-
-## Languages and Platforms
-
-You can use Plandex to work with any language or framework that the underlying LLM has been trained on. For the largest models, this includes just about any language or framework you can think of, though output quality will tend to be best for those that are more popular and therefore better represented in the training data.
-
-Plandex is cross-platform and easy to install. It supports Mac, Linux, FreeBSD, and Windows. It runs from a single binary with no dependencies.
-
-## Hosting
-
-Plandex runs on a client-server architecture. The Plandex server is open source and can be self-hosted. A cloud-hosted option is also offered for getting started as quickly as possible with minimal setup.
-
-## Community
-
-Join our growing community and help guide Plandex's development.
-
-- [GitHub](https://github.com/plandex-ai/plandex) - post an [issue](https://github.com/plandex-ai/plandex/issues), start a [discussion](https://github.com/plandex-ai/plandex/discussions), or [fork and contribute.](https://github.com/plandex-ai/plandex/fork)
-- [Discord](https://discord.gg/plandex-ai) - ask for help, give feedback, share your use cases, or just hang out.
-- [X](https://x.com/PlandexAI) - follow for updates on new versions and other AI coding content.
-- [YouTube](https://www.youtube.com/@plandex-ny5ry) - subscribe to watch various tasks and projects get completed with Plandex.
diff --git a/docs/docs/models/model-providers.md b/docs/docs/models/model-providers.md
index be7aa2af..1766368e 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 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.
+By default, Plandex uses a mix of Anthropic, OpenAI, and Google models. OpenAI models call the OpenAI API directly, while all other models are called via [OpenRouter.ai](https://openrouter.ai/).
-## Limitations
+You can also use Plandex with models from any provider that provides an OpenAI-compatible API, like the aforementioned [OpenRouter.ai](https://openrouter.ai/), [Together.ai](https://together.ai), [Replicate](https://replicate.com/), [Ollama](https://ollama.com/), and more.
-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.
+## Model Performance
-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.
+While you can use Plandex with many different providers and models as described above, Plandex's prompts have mainly been written and tested against the built-in models and model packs, so you should expect them to give the best results.
-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.**
+## Built-in Models and Model Packs
+
+Plandex provides a curated set of built-in models and model packs.
+
+You can see the list of available model packs with:
+
+```bash
+\model-packs # REPL
+plandex model-packs # CLI
+```
+
+You can see the list of available models with:
+
+```bash
+\models available # REPL
+plandex models available # CLI
+```
## Integrated Models
@@ -43,7 +59,7 @@ Once you've created an OpenAI account, [generate an API key here.](https://platf
## Other Providers
-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.
+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
@@ -67,4 +83,4 @@ If you have multiple OpenAI orgs, you can specify which org to use:
```bash
export OPENAI_ORG_ID=... # optional - set the OpenAI OrgID if you have multiple orgs
-```
\ No newline at end of file
+```
diff --git a/docs/docs/models/model-settings.md b/docs/docs/models/model-settings.md
index 5e6913c7..319072e1 100644
--- a/docs/docs/models/model-settings.md
+++ b/docs/docs/models/model-settings.md
@@ -14,36 +14,34 @@ You can see the current plan's models and model settings with the `models` comma
```bash
plandex models # show the current AI models and model settings
plandex models available # show all available models
-plandex set-model # select from a list of models and settings
-plandex set-model planner openrouter/anthropic/claude-3.7-sonnet # set the main planner model to Claude Sonnet 3.5 from OpenRouter.ai
+plandex set-model # select from a list of models, model packs, and settings
+plandex set-model planner openrouter/anthropic/claude-3.7-sonnet # set the main planner model to Claude Sonnet 3.7 from OpenRouter.ai
plandex set-model builder temperature 0.1 # set the builder model's temperature to 0.1
plandex set-model max-tokens 4000 # set the planner model overall token limit to 4000
plandex set-model max-convo-tokens 20000 # set how large the conversation can grow before Plandex starts using summaries
```
-## Model Defaults 
+## Model Defaults 
`set-model` updates model settings for the current plan. If you want to change the default model settings for all new plans, use `set-model default`.
```bash
plandex models default # show the default model settings
plandex set-model default # select from a list of models and settings
-plandex set-model default planner openai/gpt-4 # set the default planner model to OpenAI gpt-4
+plandex set-model default planner openai/gpt-4o # set the default planner model to OpenAI gpt-4o
```
-## Custom Models
+## Model Packs
-Use `models add` to add a custom model and use any provider that is compatible with OpenAI, including OpenRouter.ai, Together.ai, Ollama, Replicate, and more.
+Instead of changing models for each role one by one, model packs let you switch out all roles at once. It's the recommended way to manage models.
+
+You can list available model packs with `model-packs`:
```bash
-plandex models add # add a custom model
-plandex models available --custom # show all available custom models
-plandex models delete # delete a custom model
+plandex model-packs # list all available model packs
```
-## Model Packs
-
-Instead of changing models for each role one by one, a model pack lets you switch out all roles at once. You can create your own model packs with `model-packs create`, list built-in and custom model packs with `model-packs`, and remove custom model packs with `model-packs delete`.
+You can create your own model packs with `model-packs create`, list built-in and custom model packs with `model-packs`, and remove custom model packs with `model-packs delete`.
```bash
plandex set-model # select from a list of model packs for the current plan
@@ -54,4 +52,14 @@ plandex set-model default Mixtral-8x22b/Mixtral-8x7b/gpt-4o # set the default mo
plandex model-packs # list built-in and custom model packs
plandex model-packs create # create a new custom model pack
plandex model-packs --custom # list only custom model packs
-```
\ No newline at end of file
+```
+
+## Custom Models
+
+Use `models add` to add a custom model and use any provider that is compatible with OpenAI, including OpenRouter.ai, Together.ai, Ollama, Replicate, and more.
+
+```bash
+plandex models add # add a custom model
+plandex models available --custom # show all available custom models
+plandex models delete # delete a custom model
+```
diff --git a/docs/docs/models/roles.md b/docs/docs/models/roles.md
index 69f74d52..a94384a3 100644
--- a/docs/docs/models/roles.md
+++ b/docs/docs/models/roles.md
@@ -5,52 +5,60 @@ sidebar_label: Roles
# Model Roles
-Plandex has multiple **roles** that are used for different aspects of its functionality. Each role can have its model and settings changed independently. These are the roles:
+Plandex has multiple **roles** that are used for different aspects of its functionality. Each role can have its model and settings changed independently.
+
+## Roles
### `planner`
-This is the 'main' model that replies to prompts and makes plans.
+This is the 'main' role that replies to prompts and makes plans.
-Requires streaming support.
+Can optionally have a 'large context fallback' set, which is the model to use when the context input limit is exceeded.
-### `summarizer`
+### `architect`
-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).
+When auto-context is enabled, this role makes a high-level plan using the project map, then determines what context to to provide for the 'planner' role.
-### `auto-continue`
+This role is optional. It falls back to the `planner` role if not set.
-Determines whether a plan is finished or should automatically continue based on the previous response and the `summarizer` role's latest summary.
+### `coder`
-Requires function calling support.
+This role writes code to implement each step of the plan made by the `planner` role during the planning stage.
-### `builder`
+Instruction-following is important for this role as it needs to follow specific formatting rules.
-Builds the proposed changes described by the `planner` role into pending file updates.
+This role is optional. It falls back to the `planner` role if not set.
+
+### `summarizer`
-### `verifier`
+Summarizes conversations to stay under the limit set in `max-convo-tokens`.
-Verifies correctness of file updates produced by the `builder` role. Defaults to the same model and settings as the `builder` role.
+### `auto-continue`
-Requires function calling support.
+Determines whether a plan is finished or should automatically continue based on the previous response.
-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).
+### `builder`
-### `auto-fix`
+Builds the proposed changes described by the `planner` role into pending file updates.
-Fixes syntax errors, as well as other problems identified by the `verifier` role. Defaults to the same model and settings as the `builder` role.
+### `whole-file-builder`
-Requires function calling support.
+Builds the proposed changes described by the `planner` role into pending file updates by writing the entire file. Used as a fallback if more targeted edits fail.
-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).
+This role is optional. It falls back to the `builder` role if not set.
### `names`
Gives automatically-generated names to plans and context.
-Requires function calling support.
-
### `commit-messages`
Automatically generates commit messages for a set of pending updates.
-Requires function calling support.
+## Fallbacks and Variants
+
+- Roles can optionally have a 'large context fallback' set, which is an alternate model with a large context window to use when the context input limit is exceeded.
+
+- They can also have a 'large output fallback' set, which is an alternate model with a large output window to use when the output limit is exceeded.
+
+- They can also have a 'strong' variant set, which is an alternative model with stronger capabilities that may be used in some cases when the default model for the role is struggling.
diff --git a/docs/docs/quick-start.md b/docs/docs/quick-start.md
index 51597208..98dbe2b0 100644
--- a/docs/docs/quick-start.md
+++ b/docs/docs/quick-start.md
@@ -1,5 +1,5 @@
---
-sidebar_position: 3
+sidebar_position: 2
sidebar_label: Quickstart
---
@@ -8,7 +8,7 @@ sidebar_label: Quickstart
## Install Plandex
```bash
-curl -sL https://plandex.ai/install.sh | bash
+curl -sL https://v2.plandex.ai/install.sh | bash
```
[Click here for more installation options.](./install.md)
@@ -17,11 +17,11 @@ Note that Windows is supported via [WSL](https://learn.microsoft.com/en-us/windo
## Hosting Options
-| 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 |
+| ------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **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. |
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:
@@ -38,13 +38,13 @@ If you're starting on a new project, make a directory first:
mkdir your-project-dir
```
-Now `cd` into your **project's directory.**
+Now `cd` into your **project's directory.**
```bash
cd your-project-dir
```
-Then just give a quick the REPL help text a quick read, and you're ready go. The REPL starts in *chat mode* by default, which is good for fleshing out ideas before moving to implementation. Once the task is clear, Plandex will prompt you to switch to *tell mode* to make a detailed plan and start writing code.
+Then just give a quick the REPL help text a quick read, and you're ready go. The REPL starts in _chat mode_ by default, which is good for fleshing out ideas before moving to implementation. Once the task is clear, Plandex will prompt you to switch to _tell mode_ to make a detailed plan and start writing code.
```bash
plandex
@@ -56,29 +56,6 @@ or for short:
pdx
```
-☁️ *If you're using Plandex Cloud, you'll be prompted at this point to start a trial.*
+☁️ _If you're using Plandex Cloud, you'll be prompted at this point to start a trial._
Then just give a quick the REPL help text a quick read, and you're ready go.
-
-## REPL Flags
-
-The REPL has a few convenient flags you can use to start it with different modes, autonomy settings, and model packs. You can pass any of these to `plandex` or `pdx` when starting the REPL.
-
-```
- Mode
- --chat, -c Start in chat mode (for conversation without making changes)
- --tell, -t Start in tell mode (for implementation)
-
- Autonomy
- --no-auto None → step-by-step, no automation
- --basic Basic → auto-continue plans, no other automation
- --plus Plus → auto-update context, smart context, auto-commit changes
- --semi Semi-Auto → auto-load context
- --full Full-Auto → auto-apply, auto-exec, auto-debug
-
- Models
- --daily Daily driver pack (default models, balanced capability, cost, and speed)
- --strong Strong pack (more capable models, higher cost and slower)
- --cheap Cheap pack (less capable models, lower cost and faster)
- --oss Open source pack (open source models)
-```
\ No newline at end of file
diff --git a/docs/docs/repl.md b/docs/docs/repl.md
new file mode 100644
index 00000000..e57123b3
--- /dev/null
+++ b/docs/docs/repl.md
@@ -0,0 +1,52 @@
+---
+sidebar_position: 3
+sidebar_label: REPL
+---
+
+# REPL
+
+The Plandex REPL is a developer-friendly chat interface. It's the easiest way to use Plandex.
+
+## Start
+
+To start the REPL, just run `plandex` or `pdx` in any project directory (or sub-directory).
+
+If you don't have a current plan in the directory, the REPL will create a new one. Otherwise, it will use the current plan.
+
+## Commands
+
+All Plandex CLI commands are available in the REPL. Just type a backslash (`\`) followed by the command.
+
+The REPL also has a few special commands of its own:
+
+- `\quit` or `\q` to quit the REPL
+- `\help` or `\h` for help
+- `@` plus a relative file path for loading files into context (note that if you're using auto-context mode, loading files yourself is optional)
+- `\run` or `\r` plus a relative file path for using a file as a prompt
+- `\chat` or `\ch` to switch to chat mode and have a conversation without making changes
+- `\tell` or `\t` to switch to tell mode and implement tasks
+- `\multi` or `\m` to switch to multi-line mode
+- `\send` or `\s` to send the current prompt to Plandex (for sending a prompt in multi-line mode, since enter gives you a newline)
+
+## REPL Flags
+
+The REPL has a few convenient flags you can use to start it with different modes, autonomy settings, and model packs. You can pass any of these to `plandex` or `pdx` when starting the REPL.
+
+```
+ Mode
+ --chat, -c Start in chat mode (for conversation without making changes)
+ --tell, -t Start in tell mode (for implementation)
+
+ Autonomy
+ --no-auto None → step-by-step, no automation
+ --basic Basic → auto-continue plans, no other automation
+ --plus Plus → auto-update context, smart context, auto-commit changes
+ --semi Semi-Auto → auto-load context
+ --full Full-Auto → auto-apply, auto-exec, auto-debug
+
+ Models
+ --daily Daily driver pack (default models, balanced capability, cost, and speed)
+ --strong Strong pack (more capable models, higher cost and slower)
+ --cheap Cheap pack (less capable models, lower cost and faster)
+ --oss Open source pack (open source models)
+```