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
lots of work on docs--still wip
Dane Schneiderb0e6e587f6d3
diff --git a/docs/docs/cli-reference.md b/docs/docs/cli-reference.mdindex 8d0f8d18..b7dc2252 100644--- a/docs/docs/cli-reference.md+++ b/docs/docs/cli-reference.md@@ -3,71 +3,457 @@ sidebar_position: 6sidebar_label: CLI Reference----# Command List+# CLI Reference-This section provides a comprehensive list of all Plandex CLI commands.+All Plandex CLI commands and their options.-## General Commands+## Usage-- `plandex new`: Start a new plan.-- `plandex load`: Load files, directories, URLs, notes, or piped data into context.-- `plandex tell`: Describe a task, ask a question, or chat.-- `plandex changes`: Review pending changes in a TUI.-- `plandex diff`: Review pending changes in 'git diff' format.-- `plandex apply`: Apply pending changes to project files.-- `plandex reject`: Reject pending changes to one or more project files.+```bash+plandex [command] [flags]+pdx [command] [flags] # 'pdx' is an alias for 'plandex'+```-## Plan Management+## Help-- `plandex plans`: List plans.-- `plandex cd`: Set current plan by name or index.-- `plandex current`: Show current plan.-- `plandex delete-plan`: Delete a plan by name or index.-- `plandex rename`: Rename the current plan.-- `plandex archive`: Archive a plan.-- `plandex unarchive`: Unarchive a plan.+Built-in help.-## Context Management+```bash+plandex help+pdx h # alias+```-- `plandex ls`: List everything in context.-- `plandex rm`: Remove context by index, range, name, or glob.-- `plandex update`: Update outdated context.-- `plandex clear`: Remove all context.+`--all/-a`: List all commands.-## Branch Management+For help on a specific command, use:-- `plandex branches`: List plan branches.-- `plandex checkout`: Checkout or create a branch.-- `plandex delete-branch`: Delete a branch by name or index.+```bash+plandex [command] --help+```-## History and Rewind+## Plans-- `plandex log`: Show plan history.-- `plandex rewind`: Rewind to a previous state.-- `plandex convo`: Show plan conversation.+### new-## Background Tasks+Start a new plan.-- `plandex ps`: List active and recently finished plan streams.-- `plandex connect`: Connect to an active plan stream.-- `plandex stop`: Stop an active plan stream.+```bash+plandex new+plandex new -n new-plan # with name+```-## Model Management+`--name/-n`: Name of the new plan. The name is generated automatically after first prompt if no name is specified on creation.++### plans++List plans. Output includes index, when each plan was last updated, the current branch of each plan, the number of tokens in context, and the number of tokens in the conversation (prior to summarization).++Includes full details on plans in current directory. Also includes names of plans in parent directories and child directories.++```bash+plandex plans+plandex plans --archived # list archived plans only++pdx pl # alias+```++`--archived/-a`: List archived plans only.++### current++Show current plan. Output includes when the plan was last updated and created, the current branch, the number of tokens in context, and the number of tokens in the conversation (prior to summarization).++```bash+plandex current+pdx cu # alias+```++### cd++Set current plan by name or index.++```bash+plandex cd # select from a list of plans+plandex cd some-plan # by name+plandex cd 4 # by index in `plandex plans`+```++With no arguments, Plandex prompts you with a list of plans to select from.++With one argument, Plandex selects a plan by name or by index in the `plandex plans` list.++### delete-plan++Delete a plan by name or index.++```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`++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.++### rename++Rename the current plan.++```bash+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.++```bash+plandex archive # select from a list of plans+plandex archive some-plan # by name+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.++```bash+plandex unarchive # select from a list of archived plans+plandex unarchive some-plan # by name+plandex unarchive 4 # by index in `plandex plans --archived`+pdx unarc # alias+```++## Context++### load++Load files, directories, directory layouts, URLs, notes, images, or piped data into context.++```bash+plandex load component.ts # single file+plandex load component.ts action.ts reducer.ts # multiple files+plandex load lib -r # loads lib and all its subdirectories+plandex load tests/**/*.ts # loads all .ts files in tests and its subdirectories+plandex load . --tree # loads the layout of the current directory and its subdirectories (file names only)+plandex load https://redux.js.org/usage/writing-tests # loads the text-only content of the url+npm test | plandex load # loads the output of `npm test`+plandex load -n 'add logging statements to all the code you generate.' # load a note into context+plandex load ui-mockup.png # load an image into context++pdx l component.ts # alias+```++`--recursive/-r`: Load an entire directory and all its subdirectories.++`--tree`: Load directory tree layout with file names only.++`--note/-n`: Load a note into context.++`--force/-f`: Load files even when ignored by .gitignore or .plandexignore.++`--detail/-d`: Image detail level when loading an image (high or low)—default is high. See https://platform.openai.com/docs/guides/vision/low-or-high-fidelity-image-understanding for more info.++### ls++List everything in context. Output includes index, name, type, token size, when the context added, and when the context was last updated.++```bash+plandex ls+```++### rm++Remove context by index, range, name, or glob.++```bash+plandex rm++```++### update++Update outdated context.++```bash+plandex update+```++### clear++Remove all context.++```bash+plandex clear+```++## Control++### tell++Describe a task, ask a question, or chat.++```bash+plandex tell+```++### continue++Continue the plan.++```bash+plandex continue+```++### build++Build any pending changes.++```bash+plandex build+```++## Changes++### diff++Review pending changes in 'git diff' format.++```bash+plandex diff+```++### changes++Review pending changes in a TUI.++```bash+plandex changes+```++### apply++Apply pending changes to project files.++```bash+plandex apply+```++### reject++Reject pending changes to one or more project files.++```bash+plandex reject+```++## History++### log++Show plan history.++```bash+plandex log+```++### rewind++Rewind to a previous state.++```bash+plandex rewind+```++### convo++Show plan conversation.++```bash+plandex convo+```++## Branches++### branches++List plan branches.++```bash+plandex branches+```++### checkout++Checkout or create a branch.++```bash+plandex checkout+```++### delete-branch++Delete a branch by name or index.++```bash+plandex delete-branch+```++## Background Tasks / Streams++### ps++List active and recently finished plan streams.++```bash+plandex ps+```++### connect++Connect to an active plan stream.++```bash+plandex connect+```++### stop++Stop an active plan stream.++```bash+plandex stop+```+++## Models++### models++Show plan model settings.++```bash+plandex models+```++### models default++Show org-wide default model settings for new plans.++```bash+plandex models default+```++### models available++Show all available models.++```bash+plandex models available+```++### set-model++Update current plan model settings.++```bash+plandex set-model+```++### set-model default++Update org-wide default model settings for new plans.++```bash+plandex set-model default+```++### models add++Add a custom model.++```bash+plandex models add+```++### models delete++Delete a custom model.++```bash+plandex models delete+```++### model-packs++Show all available model packs.++```bash+plandex model-packs+```++### model-packs create++Create a new custom model pack.++```bash+plandex model-packs create+```++### model-packs delete++Delete a custom model pack.++```bash+plandex model-packs delete+```-- `plandex models`: Show plan model settings.-- `plandex models default`: Show org-wide default model settings for new plans.-- `plandex models available`: Show all available models.-- `plandex set-model`: Update current plan model settings.-- `plandex set-model default`: Update org-wide default model settings for new plans.-- `plandex models add`: Add a custom model.-- `plandex models delete`: Delete a custom model.-- `plandex model-packs`: Show all available model packs.-- `plandex model-packs create`: Create a new custom model pack.-- `plandex model-packs delete`: Delete a custom model pack.## Account Management-- `plandex sign-in`: Sign in, accept an invite, or create an account.-- `plandex invite`: Invite a user to join your org.-- `plandex revoke`: Revoke an invite or remove a user from your org.-- `plandex users`: List users and pending invites in your org.+### sign-in++Sign in, accept an invite, or create an account.++```bash+plandex sign-in+```++### invite++Invite a user to join your org.++```bash+plandex invite+```++### revoke++Revoke an invite or remove a user from your org.++```bash+plandex revoke+```++### users++List users and pending invites in your org.++```bash+plandex users+```+diff --git a/docs/docs/core-concepts/background-tasks.md b/docs/docs/core-concepts/background-tasks.mdindex dd7c9663..d20557bf 100644--- a/docs/docs/core-concepts/background-tasks.md+++ b/docs/docs/core-concepts/background-tasks.md@@ -1,15 +1,23 @@+---+sidebar_position: 8+sidebar_label: Background Tasks+---+# Background Tasks-Plandex allows you to run tasks in the background, enabling you to work on multiple tasks in parallel.+Plandex allows you to run tasks in the background, helping you work on multiple tasks in parallel.## Running a Task in the Background-To run a task in the background, use the `--bg` flag:+To run a task in the background, use the `--bg` flag with `plandex tell` or `plandex continue`.```bash-plandex tell --bg "Add a new feature"+plandex tell --bg "Add an update credit card form to 'src/components/billing'"+plandex continue --bg```+The plandex stream TUI also has a `b` hotkey that allows you to send a streaming plan to the background.+## Listing Background TasksTo list active and recently finished background tasks, use the `plandex ps` command:@@ -20,7 +28,7 @@ plandex ps## Connecting to a Background Task-To connect to a running background task, use the `plandex connect` command:+To connect to a running background task and view its stream in the plan stream TUI, use the `plandex connect` command:```bashplandex connectdiff --git a/docs/docs/core-concepts/branches.md b/docs/docs/core-concepts/branches.mdindex 62e7770f..3d45a631 100644--- a/docs/docs/core-concepts/branches.md+++ b/docs/docs/core-concepts/branches.md@@ -1,6 +1,16 @@+---+sidebar_position: 6+sidebar_label: Branches+---+# Branches-Branches in Plandex allow you to work on multiple tasks or approaches in parallel. Each branch can have its own context and changes.+Branches in Plandex allow you to easily try out multiple approaches to a task and see which gives you the best results. They work in conjunction with [version control](./version-control.md). Use cases include:++- Comparing different prompting strategies.+- Comparing results with different files in context.+- Comparing results with different models or model-settings.+- Using `plandex rewind` without losing history (first check out a new branch, then rewind).## Creating a Branch@@ -12,7 +22,7 @@ plandex checkout new-branch## Switching Branches-To switch to a different branch, use the `plandex checkout` command:+To switch to a different branch, also use the `plandex checkout` command:```bashplandex checkout existing-branchdiff --git a/docs/docs/core-concepts/context-management.md b/docs/docs/core-concepts/context-management.mdindex e144a2a8..84246e0c 100644--- a/docs/docs/core-concepts/context-management.md+++ b/docs/docs/core-concepts/context-management.md@@ -1,16 +1,95 @@+---+sidebar_position: 2+sidebar_label: Context+---+# Context Management-Context in Plandex refers to the files, directories, URLs, and other data that the AI uses to understand and work on your project.+Context in Plandex refers to files, directories, URLs, images, notes or piped in data that the LLM uses to understand and work on your project. Context is always associated with a [plan](./plans.md)## Loading Context-To load files or directories into context, use the `plandex load` command:+To load files, directories, directory layouts, urls, images, notes, or piped data into a plan's context, use the `plandex load` command.++### Loading Files++You can pass `load` one or more file paths. File paths are relative to the current directory in your terminal.++```bash+plandex load component.ts # single file+plandex load component.ts action.ts reducer.ts # multiple files+```++You can also load multiple files using glob patterns:++```bash+plandex load tests/**/*.ts # loads all .ts files in 'tests' and its subdirectories+```++You can load context from parent or sibling directories if needed by using `..` in your load paths.++```bash+plandex load ../file.go # loads file.go from parent directory+plandex load ../sibling-dir/test.go # loads test.go from sibling directory+```++### Loading Directories++You can load an entire directory with the `--recursive/-r` flag:++```bash+plandex load lib -r # loads lib, all its files and all its 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).++```bash+plandex load . --tree # loads the layout of the current directory and its subdirectories (file names only)+plandex load src/components --tree # loads the layout of the src/components directory+```++### Loading URLs++Plandex can load the text content of URLs, which can be useful for adding relevant documentation, blog posts, discussions, and the like.++```bash+plandex load https://redux.js.org/usage/writing-tests # loads the text-only content of the url+```++### Loading Images++Plandex can load images into context.```bash-plandex load file1.ts file2.ts-plandex load src -r # Load a directory recursively+plandex load ui-mockup.png```+For the default GPT-4o model, png, jpeg, non-animated gif, and webp formats are supported. For other models, support for images in general, and particular formats specifically, will depend on the model.++### Loading Notes++You can add notes to context, which are just simple strings.++```bash+plandex load -n 'add logging statements to all the code you generate.' # load a note into context+```++Notes can be useful as 'sticky' explanations or instructions that will tend to have more prominence throughout a long conversation than normal prompts. That's because long conversations are summarized to stay below a token limit, which can cause some details from your prompts to be dropped along the way. This doesn't happen if you use notes.++### Piping Into Context++You can pipe the results of other commands into context:++```bash+npm test | plandex load # loads the output of `npm test`+```++### Ignoring files++If you're in a git repo, Plandex respects `.gitignore` and won't load any files that you're ignoring. You can also add a `.plandexignore` file with ignore patterns to any directory.+## Viewing ContextTo list everything in context, use the `plandex ls` command:@@ -21,10 +100,14 @@ plandex ls## Removing Context-To remove context, use the `plandex rm` command:+To remove selectively remove context, use the `plandex rm` command:```bash-plandex rm file1.ts+plandex rm component.ts # remove by name+plandex rm 2 # remove by number in the `plandex ls` list+plandex rm 2-5 # remove a range of indices+plandex rm lib/**/*.js # remove by glob pattern+plandex rm lib # remove whole directory```## Clearing Context@@ -37,8 +120,8 @@ plandex clear## Updating Context-To update outdated context, use the `plandex update` command:+If files in context are modified outside of Plandex, you will be prompted to update them the next time you send a prompt. You can also update any outdated files with the `update` command.```bash-plandex update-```+plandex update # update files in context+```\ No newline at end of filediff --git a/docs/docs/core-concepts/conversations.md b/docs/docs/core-concepts/conversations.mdnew file mode 100644index 00000000..797cac56--- /dev/null+++ b/docs/docs/core-concepts/conversations.md@@ -0,0 +1,47 @@+---+sidebar_position: 7+sidebar_label: Conversations+---++# Conversations++Each time you send a prompt to Plandex or Plandex responds, the plan's **conversation** is updated.++## Conversation History++You can see the full conversation history with the `convo` command.++```bash+plandex convo # show the full conversation history+```++You can output the conversation in plain text with no ANSI codes with the `--plain` or `-p` flag.++```bash+plandex convo --plain+```++You can also show a specific message number or range of messages.++```bash+plandex convo 1 # show the initial prompt+plandex convo 1-5 # show messages 1 through 5+plandex convo 2- # show messages 2 through the end of the conversation+```++## Conversation Summaries++Every time the AI model replies, Plandex will summarize the conversation so far in the background and store the summary in case it's needed later. When the conversation size in tokens exceeds the model's limit, Plandex will automatically replace some number of older messages with the corresponding summary. It will summarize as many messages as necessary to keep the conversation size under the limit.++You can see the latest summary with the `summary` command.++```bash+plandex summary # show the latest conversation summary+```++As with the `convo` command, you can output the summary in plain text with no ANSI codes with the `--plain` or `-p` flag.++```bash+plandex summary --plain+```+diff --git a/docs/docs/core-concepts/orgs.md b/docs/docs/core-concepts/orgs.mdnew file mode 100644index 00000000..0deff2fb--- /dev/null+++ b/docs/docs/core-concepts/orgs.md@@ -0,0 +1,48 @@+---+sidebar_position: 9+sidebar_label: Collaboration / Orgs+---++# Collaboration and Orgs++While so far Plandex is mainly focused on a single-user experience, we plan to add features for sharing, collaboration, and team management in the future, and some groundwork has already been done. **Orgs** are the basis for collaboration in Plandex.++## Multiple Users++That said, orgs are helpful already if you have multiple users using Plandex in the same project. Because Plandex outputs a `.plandex` file containing a bit of non-sensitive config data in each directory a plan is created in, you'll have problems with multiple users unless you either get each user into the same org or put `.plandex` in your `.gitignore` file. Each user will overwrite other users' `.plandex` files on every push, and no one will be happy.++## Domain Access++When starting out with Plandex and creating a new org, you have the option of automatically granting access to anyone with an email address on your domain.++## Invitations++If you choose not to grant access to your whole domain, or you want to invite someone from outside your email domain, you can use `plandex invite`:++```bash+plandex invite+```++## Joining an Org++To join an org you've been invited to, use `plandex sign-in`:++```bash+plandex sign-in+```++## Listing Users and Invites++To list users and pending invites, use `plandex users`:++```bash+plandex users+```++## Reovking Users and Invites++To revoke an invite or remove a user, use `plandex revoke`:++```bash+plandex revoke+```\ No newline at end of filediff --git a/docs/docs/core-concepts/plans.md b/docs/docs/core-concepts/plans.mdindex a67405e6..ba54004a 100644--- a/docs/docs/core-concepts/plans.md+++ b/docs/docs/core-concepts/plans.md@@ -1,63 +1,105 @@+---+sidebar_position: 1+sidebar_label: Plans+---+# Plans-A plan in Plandex is a structured task that the AI will work on. Plans help you organize and manage your development tasks efficiently.+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 app.-## Creating a Plan+A plan includes:-To create a new plan, use the `plandex new` command:+- Any context that you've loaded.+- Your conversation with the model.+- Any proposed changes that have been accumulated during the course of the conversation.-```bash-plandex new-```+Plans support version control and branches.++## Creating a New Plan-You can also name your plan:+First `cd` into your **project's directory.** Make a new directory first with `mkdir your-project-dir` if you're starting on a new project.```bash-plandex new -n my-plan+cd your-project-dir```-## Viewing the Current Plan--To see the current plan, use the `plandex current` command:+Then **start your first plan** with `plandex new`.```bash-plandex current+plandex new```-## Switching Plans+## Plan Names and Drafts-To switch to a different plan, use the `plandex cd` command:+When you create a plan, Plandex will automatically name your plan after you send the first prompt, but you can also give it a name up front.```bash-plandex cd my-plan+plandex new -n foo-adapters-component```+If you don't give your plan a name up front, it will be named `draft` until you send an initial prompt. To keep things tidy, you can only have one active plan named `draft`. If you create a new draft plan, any existing draft plan will be removed.+## Listing Plans-To list all plans, use the `plandex plans` command:+When you have multiple plans, you can list them with the `plans` command.```bashplandex plans```-## Deleting a Plan+## The Current Plan-To delete a plan, use the `plandex delete-plan` command:+It's important to know what the **current plan** is for any given directory, since most Plandex commands are executed against that plan.++To check the current plan:```bash-plandex delete-plan my-plan+plandex current+```++You can change the current plan with the `cd` command:++```+plandex cd # select from a list of plans+plandex cd some-other-plan # cd to a plan by name+plandex cd 2 # cd to a plan by number in the `plandex plans` list```-## Archiving and Unarchiving Plans+## Deleting Plans-To archive a plan, use the `plandex archive` command:+You can delete a plan with the `delete-plan` command:```bash-plandex archive my-plan+plandex delete-plan # select from a list of plans to delete+plandex delete-plan some-plan # delete a plan by name+plandex delete-plan 4 # delete a plan by number in the `plandex plans` list```-To unarchive a plan, use the `plandex unarchive` command:+## Archiving Plans++You can archive plans you want to keep around but aren't currently working on with the `archive` command. You can see archived plans in the current directory with `plans --archived`. You can unarchive a plan with the `unarchive` command.```bash-plandex unarchive my-plan+plandex archive # select from a list of plans to archive+plandex archive some-plan # archive a plan by name+plandex archive 2 # archive a plan by number in the `plandex plans` list++plandex unarchive # select from a list of archived plans to unarchive+plandex unarchive some-plan # unarchive a plan by name+plandex unarchive 2 # unarchive a plan by number in the `plandex plans --archived` list```++## .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.++If multiple people are using Plandex with the same project, you should either:++- Put `.plandex/` in `.gitignore`+- **Commit** the `.plandex` directory and get everyone into the same [org](./orgs.md) in Plandex.++## 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.++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 filediff --git a/docs/docs/core-concepts/prompts.md b/docs/docs/core-concepts/prompts.mdnew file mode 100644index 00000000..094aac28--- /dev/null+++ b/docs/docs/core-concepts/prompts.md@@ -0,0 +1,181 @@+---+sidebar_position: 3+sidebar_label: Prompts+---++# Prompts++## Sending Prompts++To send a prompt to the model, use the `plandex tell` command.++You can pass it in as a file with the `--file/-f` flag:++```bash+plandex tell -f prompt.txt+```++Write it in vim:++```bash+plandex tell # tell with no arguments opens vim so you can write your prompt there+```++Or pass it inline (use enter for line breaks):++```bash+plandex tell "add a new line chart showing the number of foobars over time to components/charts.tsx"+```++## Plan Stream TUI++After you send a prompt with `plandex tell`, you'll see the plan stream TUI. The model's response(s) 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 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.++## Task Prompts++The most common prompt is a **task**. 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++You can also ask Plandex questions or chat with it about whatever you want:++```bash+plandex tell "explain every function in lib/math.ts"+```++For conversational prompts, Plandex will reply with just a single response and won't automatically continue.++Note that Plandex can sometimes be a bit over-eager to interpret conversational prompts as tasks. Its built-in prompts generally give it a bias toward action. For example, responding to a prompt like this:++```bash+plandex tell "did you forget to add the submit button?"+```++Plandex is likely to respond by implementing the missing button rather than simply answering the question. Giving an additional nudge to clarify that you're only chatting and aren't implying that you want a task to be done can help.++```bash+plandex tell "did you forget to add the submit button? don't add it--just answer yes or no."+```++## Stopping and Continuing++You can prevent Plandex from automatically continuing for multiple responses by passing the `--stop/-s` flag:++```bash+plandex tell -s "write tests for the charting helpers in lib/chart-helpers.ts"+```++Plandex will then reply with just a single response. From there, you can continue if desired with the `continue` command. Like `tell`, `continue` can also accept a `--stop/-s` flag. Without the `--stop/-s` flag, `continue` will also cause Plandex to continue automatically until the task is done. If you pass the `--stop/-s` flag, it will continue for just one more response.++```bash+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.++## 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.++You can learn more about using and interacting with background tasks [here](./background-tasks.md).++## 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) or `plandex changes` (to view them in a TUI). Once you're happy with the changes, you can apply them to your project files with `plandex apply`.++- [Learn more about reviewing changes.](./reviewing-changes.md)+- [Learn more about version control.](./version-control.md)++### Skipping builds / `plandex build`++You can skip building files when you send a prompt by passing the `--no-build` flag to `plandex tell` or `plandex continue`. This can be useful if you want to ensure that a plan is on the right track before comitting the time and tokens to build files.++```bash+plandex tell "implement sign up and sign in forms in src/components" --no-build+```++You can later build any changes that were implemented in the plan with the `plandex build` command:++```bash+plandex build+```++This will show a smaller version of the plan stream TUI that only includes the `Building Plan` section.++Like full plan streams, build streams can stopped with the `s` hotkey or sent to the background with the `b` hotkey. They can also be run fully in the background with the `--bg` flag:++```bash+plandex build --bg+```++There's one more thing to keep in mind about builds. If you send a prompt with the `--no-build` flag:++```bash+plandex tell "implement a forgot password email in src/emails" --no-build+```++Then you later send *another* prompt with `plandex tell` or continue the plan with `plandex continue` and you *don't* include the `--no-build` flag, any changes that were implemented previously but weren't built will immediately start building when the plan stream begins.++```bash+plandex tell "now implement the UI portion of the forgot password flow"+# the above will start building the changes proposed in the earlier prompt that was passed --no-build+```++## Iterating on a Plan++If you send a prompt:++```bash+plandex tell "implement a fully working and production-ready tic tac toe game, including a computer-controlled AI, in html, css, and javascript"+```++And then you want to iterate on it, whether that's to add more functionality or correct something that went off track, you have a couple options.++### Continue the convo++The most straightforward way to continue iterating is to simply send another `plandex tell` command:++```bash+plandex tell "I plan to seek VC funding for this game, so please implement a dark mode toggle and give all buttons subtle gradient fills"+```++This is generally a good approach when you're happy with the current plan and want to extend it to add more functionality.++Note, you can view the full conversation history with the `plandex convo` command:++```bash+plandex convo+```++### Rewind and iterate++Another option is to use Plandex's [version control](./version-control.md) features to rewind to the point just before your prompt was sent and then update it before sending the prompt again.++You can use `plandex log` to see the plan's history and determine which step to rewind to, then `plandex rewind` with the appropriate hash to rewind to that step:++```bash+plandex log # see the history+plandex rewind accfe9 # rewind to right before your prompt+```++This approach works well in conjunction with **prompt files**. You write your prompts in files somewhere in your codebase, then pass those to `plandex tell` using the `--file/-f` flag:++```bash+plandex tell -f prompts/tic-tac-toe.txt+```++This makes it easy to continuously iterate on your prompt using `plandex rewind` and `plandex tell` until you get a result that you're happy with.++### Which is better?++There's not necessarily one right answer on whether to use an ongoing conversation or the `rewind` approach with prompt files for iteration. Here are a few things to consider when making the choice:++- Bad results tend to beget more bad results. Rewinding and iterating on the prompt is often more effective for correcting a wayward task than continuing to send more `tell` commands. Even if you are specifically prompting the model to *correct* a problem, having the wrong approach in its context will tend to bias it toward additional errors. Using `rewind` to the give the model a clean slate can work better in these scenarios.++- Iterating on a prompt file with the `rewind` approach until you find your way to an effective prompt has another benefit: you can keep the final version of the prompt that produced a given set of changes right alongside the changes themselves in your codebase. This can be helpful for other developers (or your future self) if want to revisit a task later.++- A downside of the `rewind` approach is that it can involve re-running early steps of a plan over and over, which can be **a lot** more expensive than iterating with additional `tell` commands.\ No newline at end of filediff --git a/docs/docs/core-concepts/reviewing-changes.md b/docs/docs/core-concepts/reviewing-changes.mdnew file mode 100644index 00000000..9f2d0e5e--- /dev/null+++ b/docs/docs/core-concepts/reviewing-changes.md@@ -0,0 +1,48 @@+---+sidebar_position: 4+sidebar_label: Pending Changes+---++# Pending Changes++When you give Plandex a task, the changes aren't applied directly to your project files. Instead, they are accumulated in Plandex's version-controlled **sandbox** so that you can review them first.++## `plandex diffs` / Changes TUI++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:++```bash+plandex diff+```++Or you can view them in Plandex's changes TUI:++```bash+plandex changes+```++## 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.++To reject changes to a file (or multiple files), you can run `plandex reject` with one ore more file paths:++```bash+plandex reject+```++You can also reject changes using the `r` hotkey in the `plandex changes` TUI.++Once the bad update is rejected, copy the changes from the plan's output or run `plandex convo` to output the full conversation and copy them from there. Then apply the updates to that file yourself.++## Apply The Changes++Once you're happy with the plan's changes, you can apply them to your project files with `plandex apply`:++```bash+plandex apply+```++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.\ No newline at end of filediff --git a/docs/docs/core-concepts/rewind-and-history.md b/docs/docs/core-concepts/rewind-and-history.mddeleted file mode 100644index dba06483..00000000--- a/docs/docs/core-concepts/rewind-and-history.md+++ /dev/null@@ -1,28 +0,0 @@-# Rewind and History--Plandex allows you to rewind to a previous state and view the history of your plan.--## Rewinding--To rewind the plan to an earlier state, use the `plandex rewind` command:--```bash-plandex rewind 3 # Rewind 3 steps-plandex rewind a7c8d66 # Rewind to a specific commit-```--## Viewing History--To view the history of your plan, use the `plandex log` command:--```bash-plandex log-```--## Viewing Conversation--To view the conversation history, use the `plandex convo` command:--```bash-plandex convo-```diff --git a/docs/docs/core-concepts/version-control.md b/docs/docs/core-concepts/version-control.mdnew file mode 100644index 00000000..d6625062--- /dev/null+++ b/docs/docs/core-concepts/version-control.md@@ -0,0 +1,58 @@+---+sidebar_position: 5+sidebar_label: Version Control+---++# Version Control++Just about every aspect of a Plandex plan is version-controlled, and anything that can happen during a Plandex plan creates a new version in the plan's history. This includes:++- Adding, removing, or updating context.+- When you send a prompt.+- When Plandex responds.+- When Plandex builds a file into a pending change.+- When a file with pending changes is rejected.+- When pending changes are applied to your project.+- When models or model settings are updated.++## Viewing History++To see the history of your plan, use the `plandex log` command:++```bash+plandex log+```++## Rewinding++To rewind the plan to an earlier state, use the `plandex rewind` command:++```bash+plandex rewind # Rewind 1 step+plandex rewind 3 # Rewind 3 steps+plandex rewind a7c8d66 # Rewind to a specific step+```++## Data Loss / Branches++Note that currently, there's no way to undo a `rewind` and recover any data that may have been cleared as a result. That said, you can use `rewind` without losing any history with [branches](./branches.md). Use `plandex checkout` to a create a new branch before executing `rewind`, and the original branch will still include the history from before the `rewind`.++```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+```++## Viewing Conversation++While the Plandex history includes an entry for each message in the conversion, message content isn't included. To see the conversation history, use the `plandex convo` command:++```bash+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.++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.diff --git a/docs/docs/intro.md b/docs/docs/intro.mdindex 5db38c68..73006cf7 100644--- a/docs/docs/intro.md+++ b/docs/docs/intro.md@@ -11,7 +11,7 @@ Plandex is an open source, terminal-based AI coding engine that helps you work oIt 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.-## Overview+## A Version-Controlled SandboxPlandex 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:@@ -20,6 +20,8 @@ Plandex gives the LLM its own version-controlled staging area/sandbox (separate- 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.- Apply proposed changes to your project once you're happy with them. You can optionally group the changes together as a single commit in your git repo with an automatically generated commit message. Plandex is resilient to messy git states and will leave any work you have in-progress unaffected. You can also use Plandex in directories that are *not* git repos while still retaining all the aforementioned benefits.+## 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.diff --git a/docs/docs/models/custom-models.md b/docs/docs/models/custom-models.mddeleted file mode 100644index 80e7cca8..00000000--- a/docs/docs/models/custom-models.md+++ /dev/null@@ -1,47 +0,0 @@-# Custom Models--Plandex allows you to add and manage custom models to tailor the AI's behavior to your specific needs.--## Adding a Custom Model--To add a custom model, use the `plandex models add` command:--```bash-plandex models add-```--Follow the prompts to provide the necessary details for the custom model, such as the provider, model name, base URL, API key environment variable, and other settings.--## Deleting a Custom Model--To delete a custom model, use the `plandex models delete` command:--```bash-plandex models delete model-name-```--You can also delete a custom model by its index in the list of custom models:--```bash-plandex models delete 1-```--## Listing Custom Models--To list all custom models, use the `plandex models available --custom` command:--```bash-plandex models available --custom-```--This will display a list of all custom models that you have added.--## Using Custom Models--Once you have added a custom model, you can use it in your plans by setting it as the model for a specific role. For example, to set a custom model as the planner model, use the `plandex set-model` command:--```bash-plandex set-model planner custom-provider/model-name-```--You can also set custom models for other roles, such as builder, namer, and verifier, using the same command.diff --git a/docs/docs/models/model-providers.md b/docs/docs/models/model-providers.mdnew file mode 100644index 00000000..63b40665--- /dev/null+++ b/docs/docs/models/model-providers.md@@ -0,0 +1,54 @@+---+sidebar_position: 1+sidebar_label: Providers+---++# Model Providers++By default, Plandex uses the 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.++## OpenAI++### Account++If you don't have an OpenAI account, first [sign up here.](https://platform.openai.com/signup)++### API Key++Once you've created an OpenAI account, [generate an API key here.](https://platform.openai.com/account/api-keys)++## Other Providers++Plandex can use models from any provider that is compatible with the OpenAI API, like OpenRouter.ai (Anthropic, Gemini, and open source models), Together.ai (open source models), Replicate, Ollama, and more. You'll need to create an account and generate an API key for any other providers you plan on using.++## Environment Variables++Now that you've generated an API key, export it as an environment variable in your terminal.++```bash+export OPENAI_API_KEY=...++# optional - set api keys for any other providers you're using+export OPENROUTER_API_KEY=...+export TOGETHER_API_KEY...+```++If you're using OpenAI as your model provider, you can also set a different base URL for API calls:++```bash+export OPENAI_API_BASE=... # optional - set a different base url for OpenAI calls e.g. https://<your-proxy>/v1+```++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+```++## Limitations++While you can use Plandex with many different providers and models as described above, Plandex requires reliable function calling, which can still be a challenge to find in non-OpenAI models. Additionally, Plandex's prompts have mainly been written and tested against OpenAI models.++For these reasons, OpenAI models will tend to provide the best experience, and it's recommended to start with the defaults.++In the future, we plan to offer prompts that are tailored for different models, and we also expect that other models and providers will catch up on the reliability front. Until then, support for non-OpenAI models should generally be considered experimental.\ No newline at end of filediff --git a/docs/docs/models/model-settings.md b/docs/docs/models/model-settings.mdindex 27617f64..f30beb32 100644--- a/docs/docs/models/model-settings.md+++ b/docs/docs/models/model-settings.md@@ -1,42 +1,57 @@-# Model Settings+---+sidebar_position: 3+sidebar_label: Settings+----Plandex offers a wide range of model settings that allow you to customize the behavior of the AI.+# Model Settings-## Viewing Model Settings+## `models` and `set-model`-To view the current model settings, use the `plandex models` command:+You can see the current AI models and model settings with the `models` command and change them with the `set-model` command.```bash-plandex models+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-opus-3 # set the main planner model to Claude Opus 3 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```-## Changing Model Settings--To change the model settings, use the `plandex set-model` command:--```bash-plandex set-model planner openai/gpt-4-```+Model changes are [versioned](../core-concepts/version-control.md) and can be rewound or applied to a [branch](../core-concepts/branches.md) just like any other change.-## Default Model Settings+## Model Defaults-To view and change the default model settings for new plans, use the `plandex models default` and `plandex set-model default` commands:+`set-model` udpates 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-plandex set-model default planner openai/gpt-4+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```## Custom Models-You can add custom models using the `plandex models add` command:+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+plandex models add # add a custom model+plandex models available --custom # show all available custom models+plandex models delete # delete a custom model```-To delete a custom model, use the `plandex models delete` command:+## 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`.```bash-plandex models delete-```+plandex set-model # select from a list of model packs for the current plan+plandex set-model default # select from a list of model packs to set as the default for all new plans+plandex set-model gpt-4-turbo-latest # set the current plan's model pack by name+plandex set-model default gpt-4-turbo-latest # set the default model pack for all new plans++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 filediff --git a/docs/docs/models/roles.md b/docs/docs/models/roles.mdnew file mode 100644index 00000000..e400d9e2--- /dev/null+++ b/docs/docs/models/roles.md@@ -0,0 +1,40 @@+---+sidebar_position: 2+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:++### `planner`++This is the 'main' model that replies to prompts and makes plans.++### `summarizer`++Summarizes conversations to stay under the limit set in `max-convo-tokens`. Also keeps track of the status of a plan to help determine whether it's finished or should continue (in conjunction with the `auto-continue` role).++### `auto-continue`++Determines whether a plan is finished or should automatically continue based on the previous response and the `summarizer` role's latest summary.++### `builder`++Builds the proposed changes described by the `planner` role into pending file updates.++### `verifier`++Verifies correctness of file updates produced by the `builder` role. Defaults to the same model and settings as the `builder` role.++### `auto-fix`++Fixes syntax errors, as well as other problems identified by the `verifier` role. Defaults to the same model and settings as the `builder` role.++### `names`++Gives automatically-generated names to plans and context.++### `commit-messages`++Automatically generates commit messages for a set of pending updates.diff --git a/docs/docs/quick-start.md b/docs/docs/quick-start.mdindex 45b25761..6505bb99 100644--- a/docs/docs/quick-start.md+++ b/docs/docs/quick-start.md@@ -17,13 +17,25 @@ export OPENAI_API_KEY=...## Create A Plan-Now `cd` into your **project's directory.** Make a new directory first with `mkdir your-project-dir` if you're starting on a new project.+If you're starting on a new project, make a directory first:++```bash+mkdir your-project-dir+```++Now `cd` into your **project's directory.**```bashcd your-project-dir```-Then **create your first plan** with `plandex new`.+For a new project, you might also want to initialize a git repo. Plandex doesn't require that your project is in a git repo, but it does integrate well with git if you use it.++```bash+git init+```++Now **create your first plan** with `plandex new`.```bashplandex new@@ -36,7 +48,9 @@ Load any relevant files, directories, or urls **into the LLM's context** with `p```bashplandex load some-file.ts another-file.tsplandex load src/components -r # load a whole directory-plandex load https://raw.githubusercontent.com/plandex-ai/plandex/main/README.md+plandex load src/**/*.ts # load files matching a glob pattern+plandex load https://raw.githubusercontent.com/plandex-ai/plandex/main/README.md # load the text content of a url+plandex load images/mockup.png # load an image```## Send A Prompt@@ -61,11 +75,11 @@ plandex tell "add a new line chart showing the number of foobars over time to coPlandex will make a plan for your task and then implement that plan in code.-**The changes won't yet be applied to your project's files.** Instead, they'll accumulate in Plandex's sandbox.+**The changes won't yet be applied to your project files.** Instead, they'll accumulate in Plandex's sandbox.## Review The Changes-When Plandex has finished with your task, you can review the proposed changes with the `diff` command, which shows them in `git diff` format:+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:```bashplandex diff@@ -99,7 +113,7 @@ Seeing the conversation history can also be helpful when rewinding, since `pland### 3. Reject incorrect files.-While we're working hard to get file updates as reliable as possible, bad updates can still happen. If a plan is correct but it was 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.+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.To reject changes to a file (or multiple files), you can run `plandex reject` with the file path(s):