Skip to content

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

πŸ€– Plandex β†’ Add Autonomy and Configuration pages, and update Pending Changes and Execution pages with new settings and capabilities.

Dane Schneiderc8724bfebab6
diff --git a/docs/docs/core-concepts/autonomy.md b/docs/docs/core-concepts/autonomy.md
index cbde61b4..8b430ae5 100644
--- a/docs/docs/core-concepts/autonomy.md
+++ b/docs/docs/core-concepts/autonomy.md
@@ -1,4 +1,6 @@
+
---
sidebar_position: 2
sidebar_label: Autonomy
---
+
diff --git a/docs/docs/core-concepts/configuration.md b/docs/docs/core-concepts/configuration.md
index c2b044a1..01ced151 100644
--- a/docs/docs/core-concepts/configuration.md
+++ b/docs/docs/core-concepts/configuration.md
@@ -1,6 +1,8 @@
+
---
sidebar_position: 10
sidebar_label: Configuration
---
# Configuration
+
diff --git a/docs/docs/core-concepts/execution-and-debugging.md b/docs/docs/core-concepts/execution-and-debugging.md
index 3b87837f..6fa9cd19 100644
--- a/docs/docs/core-concepts/execution-and-debugging.md
+++ b/docs/docs/core-concepts/execution-and-debugging.md
@@ -1,3 +1,4 @@
+
---
sidebar_position: 6
sidebar_label: Execution and Debugging
@@ -5,11 +6,51 @@ sidebar_label: Execution and Debugging
# Execution and Debugging
-As of version 2.0.0, Plandex includes powerful new execution and automated debugging capabilities.
+Plandex v2 includes powerful execution and automated debugging capabilities that help you run commands and automatically fix issues when they arise.
+
+## Command Execution
+
+After applying changes to your project files, you often need to run commands to verify that the changes work as expected. Plandex can execute these commands for you and capture their output.
+
+### Execution Permissions
+
+By default, Plandex can execute commands after changes are applied. This behavior is controlled by the `can-exec` configuration setting:
+
+```bash
+plandex set-config can-exec true # Allow command execution (default)
+plandex set-config can-exec false # Disable command execution
+```
+
+If you're concerned about security, you can disable command execution entirely. When disabled, Plandex will not execute any commands, even if they're part of a plan or explicitly requested.
-`plandex debug` command that can repeatedly run any terminal command, continually making fixes based on the command's output until it succeeds.
+### Automatic Execution
-## Using `plandex debug`
+Plandex can automatically execute commands after changes are applied. This behavior is controlled by the `auto-exec` configuration setting:
+
+```bash
+plandex set-config auto-exec true # Automatically execute commands
+plandex set-config auto-exec false # Prompt before executing commands (default)
+```
+
+You can also override this setting for a specific command:
+
+```bash
+plandex apply --auto-exec # Automatically execute commands after applying changes
+plandex apply --no-exec # Don't execute commands after applying changes
+```
+
+When using `plandex tell`, `plandex continue`, or `plandex build` with the `--apply` flag, you can also control command execution:
+
+```bash
+plandex tell "add a new route" --apply --auto-exec
+plandex tell "add a new route" --apply --no-exec
+```
+
+## Debugging Commands
+
+Plandex v2 includes a powerful `plandex debug` command that can repeatedly run any terminal command, continually making fixes based on the command's output until it succeeds.
+
+### Using `plandex debug`
To use `plandex debug`, simply run it with the command you want to debug:
@@ -17,38 +58,118 @@ To use `plandex debug`, simply run it with the command you want to debug:
plandex debug 'npm test'
```
-This is a shortcut for:
+This will:
-1. Running a shell command and checking whether it succeeds or fails.
-2. If it fails, send the exit code and command output to `plandex tell`.
-3. Run `plandex apply` to apply the suggested fixes.
-4. Repeat until the command succeeds.
+1. Run the specified command and check whether it succeeds or fails
+2. If it fails, send the exit code and command output to the LLM
+3. Apply the suggested fixes to your project files
+4. Repeat until the command succeeds or the maximum number of tries is reached
-## Number of Tries
+### Number of Tries
By default, `plandex debug` will run the command up to 5 times before giving up. You can change this by providing a different number of tries as the first argument:
```bash
-plandex debug 10 'npm test'
+plandex debug 10 'npm test' # Try up to 10 times
+```
+
+You can also configure the default number of tries with the `auto-debug-tries` configuration setting:
+
+```bash
+plandex set-config auto-debug-tries 10 # Set default to 10 tries
```
-## Commands That Succeed
+### Git Integration
-If a command succeeds on the first try, `plandex debug` will exit immediately without making any model calls, so you can use it for commands that may or may not succeed on the first try.
+Like the `apply` command, `plandex debug` can automatically commit changes to git after each successful fix:
```bash
-plandex debug "echo 'ok'" # succeeds and immediately exits
+plandex debug --commit 'npm test' # Commit changes after each successful fix
+plandex debug --skip-commit 'npm test' # Don't commit changes (default)
```
-## Be Careful!!
+This behavior is also controlled by the `auto-commit` configuration setting:
-`plandex debug` is a powerful tool, but it should be used with care. Because it applies changes automatically and repeatedly without a review step, it can quickly make a large number of changes to your project. Before using it, it's a good idea to make sure you have a clean git state so that you can easily revert the changes if something goes wrong.
+```bash
+plandex set-config auto-commit true # Automatically commit changes
+plandex set-config auto-commit false # Don't automatically commit changes (default)
+```
+
+### Commands That Succeed
+
+If a command succeeds on the first try, `plandex debug` will exit immediately without making any model calls. This means you can use it for commands that may or may not succeed on the first try without worrying about unnecessary model usage.
-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.
+```bash
+plandex debug "echo 'ok'" # Succeeds and immediately exits
+```
-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.
+### Automatic Debugging
-## Alternative: Piping Into `plandex tell`
+Plandex can automatically debug failing commands after changes are applied. This behavior is controlled by the `auto-debug` configuration setting:
+
+```bash
+plandex set-config auto-debug true # Automatically debug failing commands
+plandex set-config auto-debug false # Don't automatically debug failing commands (default)
+```
+
+You can also override this setting for a specific command:
+
+```bash
+plandex apply --debug # Automatically debug failing commands after applying changes
+plandex apply --debug 10 # Automatically debug failing commands with 10 tries
+```
+
+When using `plandex tell`, `plandex continue`, or `plandex build` with the `--apply` flag, you can also control automatic debugging:
+
+```bash
+plandex tell "add a new route" --apply --debug
+plandex tell "add a new route" --apply --debug 10
+```
+
+## Common Debugging Workflows
+
+### Fixing Failing Tests
+
+One of the most common use cases for `plandex debug` is fixing failing tests:
+
+```bash
+plandex debug 'npm test'
+plandex debug 'go test ./...'
+plandex debug 'pytest'
+```
+
+### Fixing Build Errors
+
+Another common use case is fixing build errors:
+
+```bash
+plandex debug 'npm run build'
+plandex debug 'go build'
+plandex debug 'cargo build'
+```
+
+### Fixing Linting Errors
+
+You can also use `plandex debug` to fix linting errors:
+
+```bash
+plandex debug 'npm run lint'
+plandex debug 'golangci-lint run'
+plandex debug 'cargo clippy'
+```
+
+### Fixing Type Errors
+
+For TypeScript or other statically typed languages, you can use `plandex debug` to fix type errors:
+
+```bash
+plandex debug 'npm run typecheck'
+plandex debug 'tsc --noEmit'
+```
+
+## Alternative Approaches
+
+### Piping Into `plandex tell`
For a less automated approach that can accomplish the same thing, you can run your command and then pipe its output into `plandex tell`:
@@ -57,3 +178,4 @@ npm test | plandex tell 'npm test output'
```
This will work similarly to `plandex debug`, but without the automatic retries and changes. You can review the changes and then run `plandex apply` if you're happy with them.
+
diff --git a/docs/docs/core-concepts/reviewing-changes.md b/docs/docs/core-concepts/reviewing-changes.md
index 88f2ba30..6ad6a811 100644
--- a/docs/docs/core-concepts/reviewing-changes.md
+++ b/docs/docs/core-concepts/reviewing-changes.md
@@ -1,3 +1,4 @@
+
---
sidebar_position: 5
sidebar_label: Pending Changes
@@ -11,7 +12,9 @@ When you give Plandex a task, by default the changes aren't applied directly to
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`
+## Viewing Changes
+
+### `plandex diff` / `plandex diff --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:
@@ -19,17 +22,22 @@ When Plandex has finished with your task, you can review the proposed changes wi
plandex diff
```
-`--plain/-p`: Outputs the conversation in plain text with no ANSI codes.
+`--plain/-p`: Outputs the diff in plain text with no ANSI codes.
-You can also view them in a local browser UI with the `plandex diffs --ui` command:
+You can also view the changes in a local browser UI with the `plandex diff --ui` command:
```bash
-plandex diffs --ui
+plandex diff --ui
```
+The UI view offers additional options:
+
+- `--side-by-side/-s`: Show diffs in side-by-side view
+- `--line-by-line/-l`: Show diffs in line-by-line view (default)
+
## Rejecting Files
-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.
+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](#applying-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`. You'll be prompted to select which files to reject.
@@ -46,7 +54,7 @@ plandex reject file1.ts file2.ts
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
+## Applying Changes
Once you're happy with the plan's changes, you can apply them to your project files with `plandex apply`:
@@ -54,16 +62,130 @@ Once you're happy with the plan's changes, you can apply them to your project fi
plandex apply
```
+### Apply Flags
+
+Plandex 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`)
+- `--debug`: Automatically execute and debug failing commands (optionally specify number of triesβ€”default is 5, based on config values `auto-debug` and `auto-debug-tries`)
+- `--commit/-c`: Commit changes to git after applying (defaults to config value `auto-commit`)
+- `--skip-commit`: Don't commit changes to git (defaults to opposite of config value `auto-commit`)
+
+### Git Integration
+
If you're in a git repository, Plandex will give you the option of grouping the changes into a git commit with an automatically generated commit message. Any uncommitted changes that were present in your working directory beforehand will be unaffected.
-You can skip the `plandex apply` confirmation with the `-y` flag.
+You can control git integration with these flags:
+
+```bash
+plandex apply --commit # Commit changes to git after applying
+plandex apply --skip-commit # Don't commit changes to git
+```
-You can pass the `--commit/-c` flag to commit the changes to git after applying them without confirmation.
+### Command Execution
-You can pass the `--skip-commit` flag to prevent the changes from being committed to git after applying them without confirmation.
+After 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.
+
+```bash
+plandex apply --auto-exec # Automatically execute commands after successful apply
+plandex apply --no-exec # Don't execute commands after successful apply
+```
+
+### Automatic Debugging
+
+If a command fails after applying changes, Plandex can automatically attempt to debug and fix the issue:
+
+```bash
+plandex apply --debug # Automatically debug failing commands (default 5 tries)
+plandex apply --debug 10 # Automatically debug failing commands with 10 tries
+```
## Auto-Applying Changes
+If you want to skip the review step and automatically apply the changes from a plan immediately after it's complete, you can pass the `--apply/-a` flag to `plandex tell`, `plandex continue`, or `plandex build`:
+
+```bash
+plandex tell "add a new route" --apply
+plandex continue --apply
+plandex build --apply
+```
+
+You can combine this with other flags:
+
+```bash
+plandex tell "add a new route" --apply --commit # Apply and commit changes
+plandex tell "add a new route" --apply --auto-exec # Apply and execute commands
+plandex tell "add a new route" --apply --debug # Apply and debug failing commands
+```
+
+## Configuration Settings
+
+Plandex v2 introduces several configuration settings that control how changes are applied. You can view these settings with `plandex config`:
+
+```bash
+plandex config
+```
+
+The following settings affect how changes are applied:
+
+- `auto-apply`: Whether changes are automatically applied after a plan is complete
+- `auto-exec`: Whether commands are automatically executed after changes are applied
+- `auto-debug`: Whether failing commands are automatically debugged
+- `auto-debug-tries`: Number of tries for automatic debugging (default: 5)
+- `auto-commit`: Whether changes are automatically committed to git after applying
+- `can-exec`: Whether commands can be executed at all (safety setting)
+
+You can modify these settings with `plandex set-config`:
+
+```bash
+plandex set-config auto-apply true
+plandex set-config auto-exec true
+plandex set-config auto-debug true
+plandex set-config auto-debug-tries 10
+plandex set-config auto-commit true
+plandex set-config can-exec true
+```
+
+## Interaction with Autonomy Levels
+
+The 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` | ❌ | ❌ | βœ… | βœ… | βœ… |
+
+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.
+
+For other autonomy levels, you'll need to manually apply changes, but you can still use the flags described above to override the default behavior for a specific command.
+
+## Recommended Workflow
+
+For most users, we recommend the following workflow:
+
+1. Use `plandex tell` to give Plandex a task
+2. Review the proposed changes with `plandex diff` or `plandex diff --ui`
+3. Apply the changes with `plandex apply`
+4. If commands need to be executed, decide whether to execute them automatically or manually
+
+For users who want more automation, we recommend:
+
+1. Set the autonomy level to `full` with `plandex set-auto full`
+2. Use `plandex tell` to give Plandex a task
+3. Let Plandex automatically apply changes, execute commands, and debug failing commands
+
+For users who want more control, we recommend:
+
+1. Set the autonomy level to `plus` or `semi` with `plandex set-auto plus` or `plandex set-auto semi`
+2. Use `plandex tell` to give Plandex a task
+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 do this, you can also pass the `--commit/-c` flag to commit the automatically applied changes to git.