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
working on remaining docs pages
Dane Schneidera4e98d6aaebe
diff --git a/docs/docs/core-concepts/autonomy.md b/docs/docs/core-concepts/autonomy.mdindex 747aa234..5f37029f 100644--- a/docs/docs/core-concepts/autonomy.md+++ b/docs/docs/core-concepts/autonomy.md@@ -1,4 +1,3 @@----sidebar_position: 2sidebar_label: Autonomy@@ -6,32 +5,31 @@ sidebar_label: Autonomy# Autonomy Levels-Plandex v2 offers five autonomy levels that control how much automation is applied during your workflow.--## Overview+Plandex v2 offers five different levels of autonomy. Each autonomy level controls:-Each autonomy level controls:-- Context loading and management-- Plan continuation-- Building changes into pending updates-- Applying changes to project files-- Command execution and debugging-- Git integration+- Automatic context loading and management+- Automatic plan continuation+- Automatic building of changes into pending updates+- Automatic application of changes to project files+- Automatic command execution and debugging+- Automatic git commits after changes are applied successfully## The Five Autonomy Levels### NoneComplete manual control with no automation:+- Manual context loading- Manual plan continuation- Manual building of changes- Manual application of changes- Manual command execution-### Basic+### Basic (equivalent to Plandex v1 autonomy level)Minimal automation:+- Manual context loading- Auto-continue plans until completion- Manual building of changes@@ -41,18 +39,20 @@ Minimal automation:### PlusSmart context management:+- Manual initial context loading- Auto-continue plans until completion-- Smart context management (only loads necessary files)+- Smart context management (only loads necessary files during implementation steps)- Auto-update context when files change- Auto-build changes into pending updates- Manual application of changes- Manual command execution- Auto-commit changes to git when applied-### Semi+### Semi (default level)Automatic context loading:+- Auto-load context using project map- Auto-continue plans until completion- Smart context management@@ -65,6 +65,7 @@ Automatic context loading:### FullComplete automation:+- Auto-load context using project map- Auto-continue plans until completion- Smart context management@@ -75,7 +76,7 @@ Complete automation:- Auto-debug failing commands- Auto-commit changes to git when applied-## Feature Comparison+## Autonomy Matrix| Feature | None | Basic | Plus | Semi | Full || --------------------- | ---- | ----- | ---- | ---- | ---- |@@ -135,23 +136,22 @@ plandex new --full # Create with 'Full'\set-auto full # Set to Full-Auto```-### Using Configuration+### Custom Autonomy Config-You can also set individual configuration options:+For more details on configuration options, see the [Configuration](./configuration.md) page.++You can give a plan custom autonomy settings by setting config values directly:```bashplandex set-config auto-continue trueplandex set-config auto-build trueplandex set-config auto-load-context true-# etc.```For more details on configuration options, see the [Configuration](./configuration.md) page.-## Recommended Workflow+## Safety++Be extremely careful with full auto mode! It can make many changes quickly without any prompting or review, and can run commands that could potentially be destructive to your system.-- New users: Start with basic or plus to learn how Plandex works-- Experienced users: Use semi or full for maximum efficiency-- Critical production tasks: Use lower autonomy levels for careful review-- Exploratory tasks: Use full for quick iteration and experimentation-+It's a good idea to make sure your git state is clean, and to check out an isolated branch before running these commands.diff --git a/docs/docs/core-concepts/configuration.md b/docs/docs/core-concepts/configuration.mdindex faa3664c..94034e79 100644--- a/docs/docs/core-concepts/configuration.md+++ b/docs/docs/core-concepts/configuration.md@@ -26,33 +26,26 @@ plandex set-config default auto-mode basic # Set default for new plans### Autonomy Settings-| Setting | Description | Default |-| ------- | ----------- | ------- |-| `auto-mode` | Overall autonomy level (`none`, `basic`, `plus`, `semi`, `full`) | `basic` |-| `auto-continue` | Continue plans until completion | `true` |-| `auto-build` | Build changes into pending updates | `true` |-| `auto-load-context` | Load context using project map | `false` |-| `smart-context` | Load only necessary files for each step | `false` |-| `auto-update-context` | Update context when files change | `false` |-| `auto-apply` | Apply changes to project files | `false` |-| `auto-exec` | Execute commands after applying changes | `false` |-| `auto-debug` | Debug failing commands | `false` |-| `auto-commit` | Commit changes to git when applied | `false` |+| Setting | Description | Default |+| --------------------- | ---------------------------------------------------------------- | ------- |+| `auto-mode` | Overall autonomy level (`none`, `basic`, `plus`, `semi`, `full`) | `basic` |+| `auto-continue` | Continue plans until completion | `true` |+| `auto-build` | Build changes into pending updates | `true` |+| `auto-load-context` | Load context using project map | `false` |+| `smart-context` | Load only necessary files for each step | `false` |+| `auto-update-context` | Update context when files change | `false` |+| `auto-apply` | Apply changes to project files | `false` |+| `auto-exec` | Execute commands after applying changes | `false` |+| `auto-debug` | Debug failing commands | `false` |+| `auto-commit` | Commit changes to git when applied | `false` |### Execution Settings-| Setting | Description | Default |-| ------- | ----------- | ------- |-| `can-exec` | Allow command execution (safety setting) | `true` |-| `auto-debug-tries` | Number of tries for automatic debugging | `5` |-| `auto-revert-on-rewind` | Revert project files when rewinding | `true` |--### Context Settings--| Setting | Description | Default |-| ------- | ----------- | ------- |-| `context-dir` | Base directory for auto-loading context | `.` |-| `max-convo-tokens` | Max tokens in conversation before summarizing | `20000` |+| Setting | Description | Default |+| ----------------------- | ---------------------------------------- | ------- |+| `can-exec` | Allow command execution (safety setting) | `true` |+| `auto-debug-tries` | Number of tries for automatic debugging | `5` |+| `auto-revert-on-rewind` | Revert project files when rewinding | `true` |## Setting Autonomy Levels@@ -74,17 +67,17 @@ plandex set-auto default semi # Set default to semi-auto## Autonomy Level Comparison-| Setting | None | Basic | Plus | Semi | Full |-| ------- | ---- | ----- | ---- | ---- | ---- |-| `auto-continue` | ❌ | ✅ | ✅ | ✅ | ✅ |-| `auto-build` | ❌ | ❌ | ✅ | ✅ | ✅ |-| `auto-load-context` | ❌ | ❌ | ❌ | ✅ | ✅ |-| `smart-context` | ❌ | ❌ | ✅ | ✅ | ✅ |-| `auto-update-context` | ❌ | ❌ | ✅ | ✅ | ✅ |-| `auto-apply` | ❌ | ❌ | ❌ | ❌ | ✅ |-| `auto-exec` | ❌ | ❌ | ❌ | ❌ | ✅ |-| `auto-debug` | ❌ | ❌ | ❌ | ❌ | ✅ |-| `auto-commit` | ❌ | ❌ | ✅ | ✅ | ✅ |+| Setting | None | Basic | Plus | Semi | Full |+| --------------------- | ---- | ----- | ---- | ---- | ---- |+| `auto-continue` | ❌ | ✅ | ✅ | ✅ | ✅ |+| `auto-build` | ❌ | ❌ | ✅ | ✅ | ✅ |+| `auto-load-context` | ❌ | ❌ | ❌ | ✅ | ✅ |+| `smart-context` | ❌ | ❌ | ✅ | ✅ | ✅ |+| `auto-update-context` | ❌ | ❌ | ✅ | ✅ | ✅ |+| `auto-apply` | ❌ | ❌ | ❌ | ❌ | ✅ |+| `auto-exec` | ❌ | ❌ | ❌ | ❌ | ✅ |+| `auto-debug` | ❌ | ❌ | ❌ | ❌ | ✅ |+| `auto-commit` | ❌ | ❌ | ✅ | ✅ | ✅ |## Command Line Overrides@@ -104,10 +97,3 @@ These overrides apply only to the current command execution and don't change the\set-config # Modify current plan config\set-auto # Set autonomy level```--## Configuration Storage--- **Per-Plan Configuration**: Stored in the plan's metadata in the `.plandex` directory-- **Global Default Configuration**: Stored in `~/.plandex/config.json`--For more details on autonomy levels, see the [Autonomy](./autonomy.md) page.diff --git a/docs/docs/core-concepts/execution-and-debugging.md b/docs/docs/core-concepts/execution-and-debugging.mdindex 68a5196b..047f97ac 100644--- a/docs/docs/core-concepts/execution-and-debugging.md+++ b/docs/docs/core-concepts/execution-and-debugging.md@@ -1,4 +1,3 @@----sidebar_position: 6sidebar_label: Execution and Debugging@@ -6,11 +5,11 @@ sidebar_label: Execution and Debugging# Execution and Debugging-Plandex v2 includes powerful execution and automated debugging capabilities to help you run commands and fix issues automatically.+Plandex v2 includes powerful execution control and automated debugging capabilities.## Command Execution-### Execution Permissions+### Execution ConfigControl whether Plandex can execute commands:@@ -47,10 +46,12 @@ plandex debug 10 'npm test' # Try up to 10 times```This will:+1. Run the command and check for success/failure2. If it fails, send the output to the LLM-3. Apply suggested fixes to your project files-4. Repeat until success or max tries reached+3. Tentatively apply suggested fixes to your project files+4. If command is succesful after fixes, commit changes (if auto-commit is enabled). Otherwise, roll back changes and return to step 2.+5. Repeat until success or max tries reached### Number of Tries@@ -60,18 +61,6 @@ Configure the default number of tries:plandex set-config auto-debug-tries 10 # Set default to 10 tries```-### Git Integration--Control whether changes are committed during debugging:--```bash-plandex debug --commit 'npm test' # Commit changes after fixes-plandex debug --skip-commit 'npm test' # Don't commit changes (default)--# Global setting-plandex set-config auto-commit true # Auto-commit changes-```-### Automatic DebuggingControl whether failing commands are automatically debugged:@@ -136,12 +125,12 @@ This works similarly to `plandex debug` but without automatic retries. You can rExecution and debugging behavior is affected by your [autonomy level](./autonomy.md):-| Setting | None | Basic | Plus | Semi | Full |-| ------- | ---- | ----- | ---- | ---- | ---- |-| `auto-exec` | ❌ | ❌ | ❌ | ❌ | ✅ |-| `auto-debug` | ❌ | ❌ | ❌ | ❌ | ✅ |+| Setting | None | Basic | Plus | Semi | Full |+| ------------ | ---- | ----- | ---- | ---- | ---- |+| `auto-exec` | ❌ | ❌ | ❌ | ❌ | ✅ |+| `auto-debug` | ❌ | ❌ | ❌ | ❌ | ✅ |-With `full` autonomy, commands are automatically executed and debugged. For other levels, you need to manually execute and debug commands (or override with flags).+With `full` autonomy, commands are automatically executed and debugged after changes are applied. For other levels, you'll be prompted to approve execution and debugging.## Configuration Settings@@ -154,35 +143,8 @@ plandex set-config auto-debug true # Auto-debug failing commandsplandex set-config auto-debug-tries 10 # Set debug tries```-## Security Considerations--- Plandex only executes commands that are part of a plan or explicitly requested-- Plandex won't execute commands with elevated privileges unless explicitly requested-- You can disable command execution with `plandex set-config can-exec false`-- Always review commands before allowing them to run-- Be careful with `auto-exec` and `auto-debug` as they execute without prompting--## Recommended Workflow--### Standard Workflow-1. Use `plandex tell` to give Plandex a task-2. Review changes with `plandex diff`-3. Apply changes with `plandex apply`-4. If a command fails, use `plandex debug` to fix it--### Automated Workflow-1. Set autonomy to `full` with `plandex set-auto full`-2. Use `plandex tell` to give Plandex a task-3. Let Plandex automatically apply, execute, and debug--### Controlled Workflow-1. Set autonomy to `plus` or `semi`-2. Use `plandex tell` to give Plandex a task-3. Review changes with `plandex diff`-4. Apply changes with `plandex apply`-5. Manually execute commands-6. If a command fails, use `plandex debug` to fix it-```+## Safety-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.+Needless to say, you should be extremely careful when using `auto-exec`, `auto-debug`, and the `debug` command. They can make many changes quickly without any prompting or review, and can run commands that could potentially be destructive to your system. While the best LLMs are quite trustworthy when it comes to running commands and are unlikely to cause harm, it still pays to be cautious.+It's a good idea to make sure your git state is clean, and to check out an isolated branch before running these commands.diff --git a/docs/docs/core-concepts/reviewing-changes.md b/docs/docs/core-concepts/reviewing-changes.mdindex 6ad6a811..dede1b2a 100644--- a/docs/docs/core-concepts/reviewing-changes.md+++ b/docs/docs/core-concepts/reviewing-changes.md@@ -1,4 +1,3 @@----sidebar_position: 5sidebar_label: Pending Changes@@ -66,7 +65,6 @@ plandex applyPlandex v2 introduces several new flags for the `apply` command that give you more control over what happens after changes are applied:-- `--bg`: Run the apply operation in the background- `--auto-update-context`: Automatically update context if files have changed (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`)@@ -85,6 +83,13 @@ plandex apply --commit # Commit changes to git after applyingplandex apply --skip-commit # Don't commit changes to git```+Or you can set the `auto-commit` config value to `true` or `false` to control this behavior globally:++```bash+plandex set-config auto-commit true+plandex set-config default skip-commit true # Set the default value for new plans+```+### Command ExecutionAfter applying changes, Plandex can automatically execute commands that were part of the plan. This is useful for running tests, starting servers, or performing other actions that verify the changes work as expected.@@ -153,12 +158,12 @@ plandex set-config can-exec trueThe behavior of the `apply` command is also affected by the [autonomy level](./autonomy.md) you've set for your plan:-| Setting | None | Basic | Plus | Semi | Full |-| ------- | ---- | ----- | ---- | ---- | ---- |-| `auto-apply` | ❌ | ❌ | ❌ | ❌ | ✅ |-| `auto-exec` | ❌ | ❌ | ❌ | ❌ | ✅ |-| `auto-debug` | ❌ | ❌ | ❌ | ❌ | ✅ |-| `auto-commit` | ❌ | ❌ | ✅ | ✅ | ✅ |+| Setting | None | Basic | Plus | Semi | Full |+| ------------- | ---- | ----- | ---- | ---- | ---- |+| `auto-apply` | ❌ | ❌ | ❌ | ❌ | ✅ |+| `auto-exec` | ❌ | ❌ | ❌ | ❌ | ✅ |+| `auto-debug` | ❌ | ❌ | ❌ | ❌ | ✅ |+| `auto-commit` | ❌ | ❌ | ✅ | ✅ | ✅ |If you're using the `full` autonomy level, changes will be automatically applied to your project files, commands will be automatically executed, and failing commands will be automatically debugged.@@ -186,6 +191,6 @@ For users who want more control, we recommend:3. Review the proposed changes with `plandex diff` or `plandex diff --ui`4. Apply the changes with `plandex apply`5. Manually execute any commands that need to be run-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 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.