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
finish up docs, update readme for new docs, remove guides dir in favor of docs
Dane Schneider0029093a4523
diff --git a/README.md b/README.mdindex 366e8d8d..5ae3be60 100644--- a/README.md+++ b/README.md@@ -21,7 +21,7 @@<b>Website</b></a>· -->- <a href="./guides/USAGE.md">+ <a href="https://docs.plandex.ai/"><b>Docs</b></a>·@@ -29,13 +29,13 @@<b>Examples</b></a>·- <a href="./guides/HOSTING.md">+ <a href="https://docs.plandex.ai/hosting/self-hosting"><b>Self-Hosting</b></a>- ·+ <!-- ·<a href="./guides/DEVELOPMENT.md"><b>Development</b>- </a>+ </a> --><!-- ·<a href="https://discord.gg/plandex-ai"><b>Discord</b>@@ -52,7 +52,6 @@[](https://discord.gg/plandex-ai)[](https://github.com/plandex-ai/plandex)[](https://twitter.com/PlandexAI)-[](https://twitter.com/Danenania)</div>@@ -103,15 +102,9 @@- [Overview](#overview-)- [Install](#install)- [Get started](#get-started-)-- [Docs](./guides/USAGE.md)-- [About](#build-complex-software-with-llms-)- - [Build complex software](#build-complex-software-with-llms-)- - [Why Plandex?](#why-plandex-)- - [Plandex Cloud](#plandex-cloud-%EF%B8%8F)- - [Self-hosting](#self-hosting-)- - [Limitations and guidance](#limitationsand-guidance-%EF%B8%8F)- - [Security](#security-)- - [Privacy and data retention](#privacy-and-data-retention-%EF%B8%8F)+- [Docs](https://docs.plandex.ai/)+- [Build complex software](#build-complex-software-with-llms-)+- [Why Plandex?](#why-plandex-)- [Roadmap](#roadmap-%EF%B8%8F)- [Discussion and discord](#discussion-and-discord-)- [Contributors](#contributors-)@@ -129,41 +122,13 @@## Install 📥-### Quick Install-```bashcurl -sL https://plandex.ai/install.sh | bash```-<details>- <summary><b>Manual install</b></summary>- <br>-<p>-Grab the appropriate binary for your platform from the latest <a href="https://github.com/plandex-ai/plandex/releases">release</a> and put it somewhere in your <code>PATH</code>.-</p>-</details>--<details>-<summary><b>Build from source</b></summary>--<p>-<pre><code>git clone https://github.com/plandex-ai/plandex.git-git clone https://github.com/plandex-ai/survey.git-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-</code></pre>-</p>-</details>--<details>-<summary><b>Windows</b></summary>-<br>-<p>-Windows is supported via <a href="https://learn.microsoft.com/en-us/windows/wsl/about">WSL</a>.-</p>-</details>+**Note:** Windows is supported via [WSL](https://learn.microsoft.com/en-us/windows/wsl/install). Plandex only works correctly on Windows in the WSL shell. It doesn't work in the Windows CMD prompt or PowerShell.+[More installation options.](https://docs.plandex.ai/install)<br/>@@ -192,12 +157,15 @@ plandex new```-Load any relevant files, directories, or urls **into the LLM's context** with `plandex load`.+Load any relevant files, directories, directory layouts, urls, or images **into the LLM's context** with `plandex load`.```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 --tree # load a directory layout (file names only)+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```@@ -221,34 +189,16 @@ Or pass it inline (use enter for line breaks):plandex tell "add a new line chart showing the number of foobars over time to components/charts.tsx"```+Plandex will make a plan for your task and then implement that plan in code. **The changes won't yet be applied to your project files.** Instead, they'll accumulate in Plandex's sandbox.-After any plandex command is run, commands that could make sense to run next will be suggested. You can learn to use Plandex quickly by jumping in and following these suggestions.--You can see a list of all commands with `plandex help` or get help on a specific command with `plandex [command] --help`.--You can use the `pdx` alias instead of `plandex` to type a bit less, and most common commands have their own aliases as well.+To learn about reviewing changes, iterating on the plan, and applying changes to your project, **[continue with the full quickstart.](https://docs.plandex.ai/quick-start#review-the-changes)**<br/>## Docs 🛠️-[Here's a quick overview of the commands and functionality.](./guides/USAGE.md)--<!-- <br/>--## Help ℹ️+### [👉 Full documentation.](https://docs.plandex.ai/)-To see all available commands:--```-plandex help-```--For help on any command:--```-plandex [command] --help-``` --><br/>@@ -277,6 +227,7 @@ plandex [command] --help<br/>+<<<<<<< HEAD## Plandex Cloud ☁️Plandex Cloud is the easiest and most reliable way to use Plandex. You'll be prompted to start an anonymous trial (no email required) when you create your first plan with `plandex new`. Trial accounts are limited to 10 plans and 10 AI model replies per plan. You can upgrade to an unlimited account with your name and email.@@ -329,6 +280,8 @@ Plandex Cloud follows best practices for network and data security. And whether<br/>+=======+>>>>>>> 1e668b3 (finish up docs, update readme for new docs, remove guides dir in favor of docs)## Roadmap 🗺️🧠 Support for open source models, Google Gemini, and Anthropic Claude in addition to OpenAI ✅ released<br>@@ -361,6 +314,6 @@ Speaking of feedback, feel free to give yours, ask questions, report a bug, or jWork on tests, evals, prompts, and bug fixes is especially appreciated.-[Here's an overview on setting up a development environment.](./guides/DEVELOPMENT.md)+[Here's an overview on setting up a development environment.](https://docs.plandex.ai/development)diff --git a/docs/docs/cli-reference.md b/docs/docs/cli-reference.mdindex b7dc2252..979212ff 100644--- a/docs/docs/cli-reference.md+++ b/docs/docs/cli-reference.md@@ -1,5 +1,5 @@----sidebar_position: 6+sidebar_position: 8sidebar_label: CLI Reference---@@ -170,10 +170,12 @@ pdx l component.ts # alias### ls-List everything in context. Output includes index, name, type, token size, when the context added, and when the context was last updated.+List everything in the current plan's context. Output includes index, name, type, token size, when the context added, and when the context was last updated.```bashplandex ls++plandex list-context # longer alias```### rm@@ -181,16 +183,22 @@ plandex lsRemove context by index, range, name, or glob.```bash-plandex rm+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 remove # longer alias+plandex unload # longer alias```### update-Update outdated context.+Update any outdated context.```bashplandex update+pdx u # alias```### clear@@ -208,25 +216,48 @@ plandex clearDescribe a task, ask a question, or chat.```bash-plandex tell+plandex tell -f prompt.txt # from file+plandex tell # open vim to write prompt+plandex tell "add a cancel button to the left of the submit button" # inline++pdx t # alias```+`--file/-f`: File path containing prompt.++`--stop/-s`: Stop after a single model response (don't auto-continue).++`--no-build/-n`: Don't build proposed changes into pending file updates.++`--bg`: Run task in the background.+### continueContinue the plan.```bashplandex continue++pdx c # alias```+`--stop/-s`: Stop after a single model response (don't auto-continue).++`--no-build/-n`: Don't build proposed changes into pending file updates.++`--bg`: Run task in the background.+### build-Build any pending changes.+Build any unbuilt pending changes from the plan conversation.```bashplandex build+pdx b # alias```+`--bg`: Build in the background.+## Changes### diff@@ -251,16 +282,25 @@ Apply pending changes to project files.```bashplandex apply+pdx ap # alias```+`--yes/-y`: Skip confirmation.+### rejectReject pending changes to one or more project files.```bash-plandex reject+plandex reject file.ts # one file+plandex reject file.ts another-file.ts # multiple files+plandex reject --all # all pending files++pdx rj file.ts # alias```+`--all/-a`: Reject all pending files.+## History### log@@ -269,6 +309,9 @@ Show plan history.```bashplandex log++plandex history # alias+plandex logs # alias```### rewind@@ -276,25 +319,47 @@ plandex logRewind to a previous state.```bash-plandex rewind+plandex rewind # rewind 1 step+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 plan conversation.+Show the current plan's conversation.```bashplandex convo+plandex convo 1 # show a specific message+plandex convo 1-5 # show a range of messages+plandex convo 3- # show all messages from 3 to the end+```++`--plain/-p`: Output conversation in plain text with no ANSI codes.++### summary++Show the latest summary of the current plan.++```bash+plandex summary```+`--plain/-p`: Output summary in plain text with no ANSI codes.+## Branches### branches-List plan branches.+List plan branches. Output includes index, name, when the branch was last updated, the number of tokens in context, and the number of tokens in the conversation (prior to summarization).```bashplandex branches+pdx br # alias```### checkout@@ -302,7 +367,10 @@ plandex branchesCheckout or create a branch.```bash-plandex checkout+plandex checkout # select from a list of branches or prompt to create a new branch+plandex checkout some-branch # checkout by name or create a new branch with that name++pdx co # alias```### delete-branch@@ -310,14 +378,22 @@ plandex checkoutDelete a branch by name or index.```bash-plandex delete-branch+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```+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-List active and recently finished plan streams.+List active and recently finished plan streams. Output includes stream ID, plan name, branch name, when the stream was started, and the stream's status (active, finished, stopped, errored, or waiting for a missing file to be selected).```bashplandex ps@@ -328,23 +404,38 @@ plandex psConnect to an active plan stream.```bash-plandex connect+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```+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.+### stopStop an active plan stream.```bash-plandex stop+plandex stop # select from a list of active streams+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.++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.## Models### models-Show plan model settings.+Show current plan models and model settings.```bashplandex models@@ -352,7 +443,7 @@ plandex models### models default-Show org-wide default model settings for new plans.+Show org-wide default models and model settings for new plans.```bashplandex models default@@ -360,28 +451,64 @@ plandex models default### models available-Show all available models.+Show available models.```bash-plandex models available+plandex models available # show all available models+plandex models available --custom # show available custom models only```+`--custom`: Show available custom models only.+### set-model-Update current plan model settings.+Update current plan models or model settings.```bash-plandex set-model+plandex set-model # select from a list of models and settings+plandex set-model planner openai/gpt-4 # set the model for a role+plandex set-model gpt-4-turbo-latest # set the current plan's model pack by name (sets all model roles at once—see `model-packs` below)+plandex set-model builder temperature 0.1 # set a model setting for a role+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```+With no arguments, Plandex prompts you to select from a list of models and settings.++With arguments, can take one of the following forms:++- `plandex set-model [role] [model]`: Set the model for a role.+- `plandex set-model [model-pack]`: Set the current plan's model pack by name.+- `plandex set-model [role] [setting] [value]`: Set a model setting for a role.+- `plandex set-model [setting] [value]`: Set a model setting for the current plan.++Models are specified as `provider/model-name`, e.g. `openai/gpt-4`, `openrouter/anthropic/claude-opus-3`, `together/mistralai/Mixtral-8x22B-Instruct-v0.1`, etc.++See all the model roles [here](./models/roles.md).++Model role settings:++- `temperature`: Higher temperature means more randomness, which can produce more creativity but also more errors.+- `top-p`: Top-p sampling is a way to prevent the model from generating improbable text by only considering the most likely tokens.++Plan settings:++- `max-tokens`: The overall token limit for the planner model.+- `max-convo-tokens`: How large the conversation can grow before Plandex starts using summaries.+- `reserved-output-tokens`: The number of tokens reserved for output from the model.+### set-model defaultUpdate org-wide default model settings for new plans.```bash-plandex set-model default+plandex set-model default # select from a list of models and settings+plandex set-model default planner openai/gpt-4 # set the model for a role+# etc. — same options as `set-model` above```+Works exactly the same as `set-model` above, but sets the default model settings for all new plans instead of only the current plan.+### models addAdd a custom model.@@ -390,12 +517,16 @@ Add a custom model.plandex models add```+Plandex will prompt you for all required information to add a custom model.+### models deleteDelete a custom model.```bash-plandex models delete+plandex models delete # select from a list of custom models+plandex models delete some-model # by name+plandex models delete 4 # by index in `plandex models available --custom````### model-packs@@ -414,15 +545,18 @@ Create a new custom model pack.plandex model-packs create```+Plandex will prompt you for all required information to create a custom model pack.+### model-packs deleteDelete a custom model pack.```bashplandex model-packs delete+plandex model-packs delete some-model-pack # by name+plandex model-packs delete 4 # by index in `plandex model-packs --custom````-## Account Management### sign-in@@ -433,20 +567,26 @@ Sign in, accept an invite, or create an account.plandex sign-in```+Plandex will prompt you for all required information to sign in, accept an invite, or create an account.+### inviteInvite a user to join your org.```bash-plandex invite+plandex invite # prompt for 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`.+### revokeRevoke an invite or remove a user from your org.```bash-plandex revoke+plandex revoke # select from a list of users and invites+plandex revoke [email protected] # by email```### usersdiff --git a/docs/docs/cloud/overview.md b/docs/docs/cloud/overview.mddeleted file mode 100644index 35354272..00000000--- a/docs/docs/cloud/overview.md+++ /dev/null@@ -1,6 +0,0 @@-----sidebar_position: 1-sidebar_label: Overview------# Plandex Cloud\ No newline at end of filediff --git a/docs/docs/cloud/privacy.md b/docs/docs/cloud/privacy.mddeleted file mode 100644index 76451f88..00000000--- a/docs/docs/cloud/privacy.md+++ /dev/null@@ -1,6 +0,0 @@-----sidebar_position: 2-sidebar_label: Privacy------# Privacy\ No newline at end of filediff --git a/docs/docs/core-concepts/context-management.md b/docs/docs/core-concepts/context-management.mdindex 84246e0c..c90bc175 100644--- a/docs/docs/core-concepts/context-management.md+++ b/docs/docs/core-concepts/context-management.md@@ -7,6 +7,8 @@ sidebar_label: ContextContext 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)+Changes to context are [version controlled](./version-control.md) and can be [branched](./branches.md).+## Loading ContextTo load files, directories, directory layouts, urls, images, notes, or piped data into a plan's context, use the `plandex load` command.@@ -24,6 +26,7 @@ You can also load multiple files using glob patterns:```bashplandex load tests/**/*.ts # loads all .ts files in 'tests' and its subdirectories+plandex load * # loads all files in the current directory```You can load context from parent or sibling directories if needed by using `..` in your load paths.@@ -39,6 +42,7 @@ You can load an entire directory with the `--recursive/-r` flag:```bashplandex 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 Directory Layoutsdiff --git a/docs/docs/core-concepts/conversations.md b/docs/docs/core-concepts/conversations.mdindex 797cac56..0c489c3e 100644--- a/docs/docs/core-concepts/conversations.md+++ b/docs/docs/core-concepts/conversations.md@@ -5,7 +5,7 @@ sidebar_label: Conversations# Conversations-Each time you send a prompt to Plandex or Plandex responds, the plan's **conversation** is updated.+Each time you send a prompt to Plandex or Plandex responds, the plan's **conversation** is updated. Conversations are [version controlled](./version-control.md) and can be [branched](./branches.md).## Conversation Historydiff --git a/docs/docs/core-concepts/plans.md b/docs/docs/core-concepts/plans.mdindex ba54004a..b76829de 100644--- a/docs/docs/core-concepts/plans.md+++ b/docs/docs/core-concepts/plans.md@@ -13,7 +13,7 @@ A plan includes:- Your conversation with the model.- Any proposed changes that have been accumulated during the course of the conversation.-Plans support version control and branches.+Plans support [version control](./version-control.md) and [branches](./branches.md).## Creating a New Plandiff --git a/docs/docs/core-concepts/version-control.md b/docs/docs/core-concepts/version-control.mdindex d6625062..a1e0561e 100644--- a/docs/docs/core-concepts/version-control.md+++ b/docs/docs/core-concepts/version-control.md@@ -10,8 +10,8 @@ Just about every aspect of a Plandex plan is version-controlled, and anything th- 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 Plandex builds the plan's proposed updates to a file into a pending change.+- When pending changes are rejected.- When pending changes are applied to your project.- When models or model settings are updated.@@ -33,9 +33,9 @@ plandex rewind 3 # Rewind 3 stepsplandex rewind a7c8d66 # Rewind to a specific step```-## Data Loss / Branches+## Preventing History Loss With 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`.+Note that currently, there's no way to undo a `rewind` and recover any history 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`.```bashplandex checkout undo-changes # create a new branch called 'undo-changes'diff --git a/guides/DEVELOPMENT.md b/docs/docs/development.mdsimilarity index 50%rename from guides/DEVELOPMENT.mdrename to docs/docs/development.mdindex 0050436b..4d1010c9 100644--- a/guides/DEVELOPMENT.md+++ b/docs/docs/development.md@@ -1,4 +1,9 @@-# Plandex development 🛠️+---+sidebar_position: 10+sidebar_label: Development+---++# DevelopmentTo set up a development environment, first install dependencies:@@ -25,18 +30,26 @@ export DATABASE_URL=postgres://user:password@host:5432/plandex?sslmode=disable #export GOENV=development```-Note: [EnvKey](https://www.envkey.com/) is a good way to manage environment variables in development.+Now from the root directory, run the script in `app/scripts/dev.sh`.++On Linux, you'll want to run this as `sudo` for copying the CLI to `/usr/local/bin` after it builds:++```bash+sudo ./app/scripts/dev.sh+```-Now from the root directory of this repo, run:+You might also need sudo on MacOS if you don't have write permissions to `/usr/local/bin`, but this shouldn't be the case for most users. Assuming you have those write permissions, you can run the script without `sudo`:```bash-./dev.sh+./app/scripts/dev.sh```This creates watchers with `reflex` to rebuild both the server and the CLI when relevant files change.The server runs on port 8080 by default.-After each build, the CLI is copied to `/usr/local/bin/plandex` (which can also be changed with the environment variable `PLANDEX_OUT_DIR`) so you can use it with just `plandex` in any directory. A `pdx` alias is also created.+After each build, the CLI is copied to `/usr/local/bin/plandex-dev`so you can use it with just `plandex-dev` in any directory. A `pdxd` alias is also created. Note the difference from the `plandex` binary and `pdx` aliases which are installed for production usage—aliases are used for development to avoid overwriting the production install.++The output directory can be changed with the `PLANDEX_DEV_CLI_OUT_DIR` environment variable. The binary name can be changed with `PLANDEX_DEV_CLI_NAME` and the alias can be changed with `PLANDEX_DEV_CLI_ALIAS`.When running the Plandex CLI, set `export PLANDEX_ENV=development` to run in development mode, which connects to the development server by default.diff --git a/docs/docs/environment-variables.md b/docs/docs/environment-variables.mdnew file mode 100644index 00000000..54f22744--- /dev/null+++ b/docs/docs/environment-variables.md@@ -0,0 +1,87 @@+---+sidebar_position: 11+sidebar_label: Environment Variables+---++# Environment Variables++This is an overview of all the environment variables that can be used with Plandex.++## CLI++### LLM Providers++```bash+OPENAI_API_BASE= # Your OpenAI server, such as http://localhost:1234/v1 Defaults to empty.+OPENAI_API_KEY= # Your OpenAI key.++# optional - set API keys for any other providers you're using+export OPENROUTER_API_KEY= # Your OpenRouter.ai API key.+export TOGETHER_API_KEY = # Your Together.ai API key.+# etc.+```++### Upgrades++```bash+PLANDEX_SKIP_UPGRADE= # Set this to '1' to skip the auto-upgrade check when running the CLI.+```++### Development++Check out the [Development Guide](./development.md) for more details.++```bash+PLANDEX_ENV=development # Set this to 'development' to default to the local development server instead of Plandex Cloud when working on Plandex itself.+PLANDEX_API_HOST= # Defaults to http://localhost:8080 if PLANDEX_ENV is development, otherwise it's https://api.plandex.ai—override this to use a different host.+PLANDEX_OUT_DIR=/usr/local/bin # Where the development binary should be output when using dev.sh+PLANDEX_DEV_CLI_OUT_DIR=/usr/local/bin # Where the development binary should be output when using dev.sh+PLANDEX_DEV_CLI_NAME=plandex-dev # The name of the development binary when using dev.sh+PLANDEX_DEV_CLI_ALIAS=pdxd # The alias for the development binary when using dev.sh+GOPATH= # This should be already set to your Go folder if you've installed Golang.+```++## Server++Check out the [Self-Hosting Guide](./hosting/self-hosting.md) for more details.++### General++```bash+GOENV=development # Whether to run in development or production mode. Must be 'development' or 'production'+PLANDEX_BASE_DIR= # The base directory to read and write files. Defaults to '$HOME/plandex-server' in development mode, '/plandex-server' in production.+PORT=8080 # The port the server listens on. Defaults to 8080.+```++### docker-compose++For self-hosting with docker-compose, default environment variables are set in `app/_env`. This file should be copied to `app/.env` before running the server. You can override any of these defaults in `.env`.++```bash+PLANDEX_DATA_DIR=/var/lib/plandex/data # When using docker-compose, this is the directory *on your machine* that the Plandex server will use to store data—it will be mounted to the Docker container as a volume.+PGDATA_DIR=/var/lib/postgresql/data # Where PostgreSQL should store its data.++# Database Credentials+POSTGRES_DATABASE=plandex # Your postgres database.+POSTGRES_USER=plandex # Your postgres user.+POSTGRES_PASSWORD=plandex # Your postgres password.+```++### Other methods++If you're *not* using docker-compose, you'll need a `DATABASE_URL` environment variable that points to a PostgreSQL database. For example, if you're running PostgreSQL locally, you might set it to something like this:++```bash+DATABASE_URL=postgres://plandex:<password>@<host>:<port>/plandex?sslmode=disable+```++### SMTP++If you're running in production mode (with `GOENV=production`, typically on a remote server), you'll need SMTP credentials:++```bash+SMTP_HOST= # Youe SMTP host.+SMTP_PORT= # Set this to 1025 e.g. if you are using mailhog.+SMTP_USER= # SMTP username.+SMTP_PASSWORD= # SMTP password.+```diff --git a/docs/docs/faq.md b/docs/docs/faq.mddeleted file mode 100644index 55061ea3..00000000--- a/docs/docs/faq.md+++ /dev/null@@ -1,6 +0,0 @@-----sidebar_position: 9-sidebar_label: FAQ------# FAQ\ No newline at end of filediff --git a/docs/docs/cloud/_category_.json b/docs/docs/hosting/_category_.jsonsimilarity index 68%rename from docs/docs/cloud/_category_.jsonrename to docs/docs/hosting/_category_.jsonindex 6dc83cc8..e73fbe89 100644--- a/docs/docs/cloud/_category_.json+++ b/docs/docs/hosting/_category_.json@@ -1,5 +1,5 @@{- "label": "Plandex Cloud",+ "label": "Hosting","position": 6,"collapsible": true,"collapsed": falsediff --git a/guides/PRIVACY.md b/docs/docs/hosting/cloud.mdsimilarity index 51%rename from guides/PRIVACY.mdrename to docs/docs/hosting/cloud.mdindex b89c9a51..83d2c8fd 100644--- a/guides/PRIVACY.md+++ b/docs/docs/hosting/cloud.md@@ -1,6 +1,17 @@-# Plandex privacy and data retention 🛡️+---+sidebar_position: 1+sidebar_label: Cloud+----## Plandex Cloud+# Plandex Cloud++## Overview++Plandex Cloud is the easiest and most reliable way to use Plandex. You'll be prompted to start an anonymous trial (no email required) when you create your first plan with `plandex new`. Trial accounts are limited to 10 plans and 10 AI model replies per plan. You can upgrade to an unlimited account with your name and email.++Plandex Cloud accounts are free for now. In the future, they will cost somewhere in the $10-20 per month range.++## Privacy / Data RetentionData you send to Plandex Cloud is retained in order to debug and improve Plandex. In the future, this data may also be used to train and fine-tune models to improve performance.@@ -8,15 +19,11 @@ That said, if you delete a plan or delete your Plandex Cloud account, all associData sent to Plandex Cloud may be shared with the following third parties:-- AWS for hosting and database services. Data is encrypted in transit and at rest.-- In the future, your name and email may be shared with with a third party transactional email service and/or email marketing service in order to send you information about your account or updates on Plandex. You will be able to opt out of these emails at any time.-- When billing and payments are implemented, your name and email may be shared with our payment processor Stripe.+- [AWS](https://aws.amazon.com/) for hosting and database services. Data is encrypted in transit and at rest.+- Your name and email is shared with [Loops](https://loops.so/), an email marketing service, in order to send you updates on Plandex. You can opt out of these emails at any time with one click.+- When billing and payments are implemented, your name and email may be shared with our payment processor [Stripe](https://stripe.com/).- In the future, your name, email, and metadata on the actions you take with Plandex may be shared with a third party analytics service in order to track usage and make improvements.Apart from the above list, no other data will be shared with any other third party. The list will be updated when a specific third party is chosen for any of the above services, or if any new third party services are introduced.-Data sent to a model provider like OpenAI is subject to the model provider's privacy and data retention policies.--## Self-hosting--If you [self-host](HOSTING.md) Plandex, no data will be sent to Plandex Cloud or to any third party, except for the data you send to model providers like OpenAI.+Data sent to a model provider like OpenAI is subject to the model provider's privacy and data retention policies.\ No newline at end of filediff --git a/docs/docs/hosting/self-hosting.md b/docs/docs/hosting/self-hosting.mdnew file mode 100644index 00000000..2dd567dd--- /dev/null+++ b/docs/docs/hosting/self-hosting.md@@ -0,0 +1,177 @@+---+sidebar_position: 2+sidebar_label: Self-Hosting+---++# Self-Hosting++Plandex is open source and uses a client-server architecture. The server can be self-hosted. You can run either run it locally or on a cloud server that you control.++## Quickstart++The self-hosting quickstart requires git, docker, and docker-compose. It's designed for local use with a single user. If you instead want to run Plandex on a remote server with multiple users or orgs, continue on to the [Requirements](#requirements) section below.++1. Run the server in development mode:++```bash+git clone https://github.com/plandex-ai/plandex.git+cd plandex/app+./start_local.sh+```++2. Install the Plandex CLI if you haven't already:++```bash+curl -sL https://plandex.ai/install.sh | bash+```++3. Then run:++```bash+plandex sign-in+```++4. Follow the prompts from there to create a new account on your self-hosted server. From there, check out the more general [CLI quickstart](../quick-start.md) to get fully up and running.++## Requirements++The Plandex server requires a PostgreSQL database (ideally v14), a persistent file system, and git.++## Development vs. Production++The Plandex server can be run in development or production mode. The main differences are how authentication pins and emails are handled, and the default path for the persistent file system.++Development mode is designed for local usage with a single user. Email isn't enabled. Authentication pins are copied to the clipboard instead of sent via email, and a system notification will pop up to let you know that the pin is ready to paste. The pin will also be output to the console. In development mode, the default base directory is `$HOME/plandex-server`.++Production mode is designed for multiple users or organizations. Email is enabled and SMTP environment variables are required. Authentication pins are sent via email. In production mode, the default base directory is `/plandex-server`.++Development or production mode is set with the `GOENV` environment variable. It should be set to either `development` or `production`.++In both development and production mode, the server runs on port 8080 by default. This can be changed with the `PORT` environment variable.++## docker-compose++For local usage in development mode, you can skip setting up PostgreSQL if you use `docker-compose` with the included `docker-compose.yml` file:++```bash+git clone https://github.com/plandex-ai/plandex.git+cd plandex/app+cp _env .env+# edit .env to override any default environment variables+docker compose build+docker compose up+```++## Other Methods++### PostgreSQL Database++If you aren't using docker-compose, you'll need a PostgreSQL database. You can run the following SQL to create a user and database, replacing `user` and `password` with your own values:++```sql+CREATE USER 'user' WITH PASSWORD 'password';+CREATE DATABASE 'plandex' OWNER 'user';+GRANT ALL PRIVILEGES ON DATABASE 'plandex' TO 'user';+```++### Environment Variables++Set `GOENV` to either `development` or `production` as described above in the [Development vs. Production](#development-vs-production) section above:++```bash+export GOENV=development+```++or++```bash+export GOENV=production+```++You'll also need a `DATABASE_URL`:++```bash+export DATABASE_URL=postgres://user:password@host:5432/plandex # replace with your own database URL+```++If you're running in production mode, you'll need to connect to SMTP to send emails. Set the following environment variables:++```bash+export SMTP_HOST=smtp.example.com+export SMTP_PORT=587+export SMTP_USER=user+export SMTP_PASSWORD=password+export [email protected] # optional, if not set then SMTP_USER is used+```++In either development or production mode, the base directory for the persistent file system can optionally be overridden with the `PLANDEX_BASE_DIR` environment variable:++```bash+export PLANDEX_BASE_DIR=~/some-dir/plandex-server+```++### Using Docker Build++The server can be run from a Dockerfile at `app/Dockerfile.server`:++```bash+git clone https://github.com/plandex-ai/plandex.git+VERSION=$(cat app/server/version.txt) # or use the version you want+git checkout server/v$VERSION+cd plandex/app+mkdir ~/plandex-server # or another directory where you want to store files+docker build -t plandex-server -f Dockerfile.server .+docker run -p 8080:8080 \+ -v ~/plandex-server:/plandex-server \+ -e DATABASE_URL \+ -e GOENV \+ -e SMTP_HOST \+ -e SMTP_PORT \+ -e SMTP_USER \+ -e SMTP_PASSWORD \+ plandex-server+```++The SMTP environment variables above are only required if you're running in [production mode](#development-vs-production).++### Run From Source++You can also run the server from source:++```bash+git clone https://github.com/plandex-ai/plandex.git+cd plandex/+VERSION=$(cat app/server/version.txt) # or use the version you want+git checkout server/v$VERSION+cd app/server+export PLANDEX_BASE_DIR=~/plandex-server # or another directory where you want to store files+go run main.go+```++## Health Check++You can check if the server is running by sending a GET request to `/health`. If all is well, it will return a 200 status code.++## Create a New Account++Once the server is running and you've [installed the Plandex CLI](../install.md) on your local development machine, you can create a new account by running `plandex sign-in`:++```bash+plandex sign-in # follow the prompts to create a new account on your self-hosted server+```++## Note On Local CLI Files++If you use the Plandex CLI and then for some reason you reset the database or use a new one, you'll need to remove the local files that the CLI creates in directories where you used Plandex in order to start fresh. Otherwise, the CLI will with an account that doesn't exist in the new database and you'll get errors. This could also happen if you use Plandex Cloud and then switch to self-hosting.++To resolve this, remove the following in any directory you used the CLI in:++- `.plandex-dev` directory if you ran the CLI with `PLANDEX_ENV=development`+- `.plandex` directory otherwise++Then run `plandex sign-in` again to create a new account.++If you're still having trouble with accounts, you can also remove the following from your $HOME directory to fully reset them:++- `.plandex-home-dev` directory if you ran the CLI with `PLANDEX_ENV=development`+- `.plandex-home` directory otherwise\ No newline at end of filediff --git a/docs/docs/intro.md b/docs/docs/intro.mdindex 73006cf7..84831658 100644--- a/docs/docs/intro.md+++ b/docs/docs/intro.md@@ -11,40 +11,44 @@ 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.-## A Version-Controlled Sandbox+## 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.++## What makes Plandex different?++### Version ControlPlandex 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.-- 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+### Context ManagementApart 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.-- Load the text content of URLs into context in order to add relevant documentation or other supporting info. You can also pipe in the output of commands or add notes.- 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.-- Like other interactions with the LLM, all context updates are version-controlled in the LLM's sandbox, meaning you can try loading different context in different branches or rewind the plan state and modify context as needed to improve results.-## Use Cases+## Focus-- 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.+For now, Plandex is focused on:-## Focus+1. Planning out the changes needed to complete a task.+2. Creating or updating all the necessary files to complete that task.-For now, Plandex is focused on 1. planning out the changes needed to complete a task, and 2. creating or updating all the necessary files to complete that task. It doesn't yet do automatic execution of code or automatic selection of context—both are left to the developer.+It doesn't yet do automatic execution of code or automatic selection of context—both are left to the developer.In other words, Plandex isn't (yet) shooting for full autonomy. While we do plan to move in this direction over time, we think the current level of model capabilities make Plandex's focus a sweet spot for achieving real productivity gains.@@ -64,7 +68,7 @@ Plandex is cross-platform and easy to install. It supports Mac, Linux, FreeBSD,## Hosting-Plandex runs on a client-server architecture. The Plandex server is open source and can be self-hosted. A cloud-hosting option is also offered for getting started as quickly as possible with minimal setup.+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.## Communitydiff --git a/docs/docs/limitations.md b/docs/docs/limitations.mddeleted file mode 100644index 73ab8d83..00000000--- a/docs/docs/limitations.md+++ /dev/null@@ -1,6 +0,0 @@-----sidebar_position: 8-sidebar_label: Limitations------# Limitations\ No newline at end of filediff --git a/docs/docs/models/model-providers.md b/docs/docs/models/model-providers.mdindex 63b40665..74d7d490 100644--- a/docs/docs/models/model-providers.md+++ b/docs/docs/models/model-providers.md@@ -5,7 +5,15 @@ 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.+By default, Plandex uses OpenAI models, but you can use models from any provider that provides an OpenAI-compatible API, like [OpenRouter.ai](https://openrouter.ai/) (Anthropic, Gemini, and open source models), [Together.ai](https://together.ai) (open source models), [Replicate](https://replicate.com/), [Ollama](https://ollama.com/), and more.++## 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.**## OpenAI@@ -43,12 +51,4 @@ If you have multiple OpenAI orgs, you can specify which org to use:```bashexport 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 file+```\ No newline at end of filediff --git a/docs/docs/models/model-settings.md b/docs/docs/models/model-settings.mdindex f30beb32..b5e3b78b 100644--- a/docs/docs/models/model-settings.md+++ b/docs/docs/models/model-settings.md@@ -5,22 +5,22 @@ sidebar_label: Settings# Model Settings+Plandex gives you a number of ways to control the models and models settings used in your plans. Changes to models and model settings are [version controlled](../core-concepts/version-control.md) and can be [branched](../core-concepts/branches.md).+## `models` and `set-model`-You can see the current AI models and model settings with the `models` command and change them with the `set-model` command.+You can see the current plan's models and model settings with the `models` command and change them with the `set-model` command.```bashplandex models # show the current AI models and model settingsplandex models available # show all available modelsplandex 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 planner openrouter/anthropic/claude-3.5-sonnet # set the main planner model to Claude Sonnet 3.5 from OpenRouter.aiplandex set-model builder temperature 0.1 # set the builder model's temperature to 0.1plandex set-model max-tokens 4000 # set the planner model overall token limit to 4000plandex set-model max-convo-tokens 20000 # set how large the conversation can grow before Plandex starts using summaries```-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.-## Model Defaults`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`.@@ -48,8 +48,8 @@ Instead of changing models for each role one by one, a model pack lets you switc```bashplandex set-model # select from a list of model packs for the current planplandex 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 set-model anthropic-claude-3.5-sonnet-gpt-4o # set the current plan's model pack by name+plandex set-model default Mixtral-8x22b/Mixtral-8x7b/gpt-4o # set the default model pack for all new plansplandex model-packs # list built-in and custom model packsplandex model-packs create # create a new custom model packdiff --git a/docs/docs/quick-start.md b/docs/docs/quick-start.mdindex 6505bb99..cd7efcf5 100644--- a/docs/docs/quick-start.md+++ b/docs/docs/quick-start.md@@ -43,11 +43,12 @@ plandex new## Load In Context-Load any relevant files, directories, or urls **into the LLM's context** with `plandex load`.+Load any relevant files, directories, directory layouts, urls, or images **into the LLM's context** with `plandex load`.```bashplandex load some-file.ts another-file.tsplandex load src/components -r # load a whole directory+plandex load src --tree # load a directory layout (file names only)plandex load src/**/*.ts # load files matching a glob patternplandex load https://raw.githubusercontent.com/plandex-ai/plandex/main/README.md # load the text content of a urlplandex load images/mockup.png # load an image@@ -73,9 +74,7 @@ Or pass it inline (use enter for line breaks):plandex tell "add a new line chart showing the number of foobars over time to components/charts.tsx"```-Plandex will make a plan for your task and then implement that plan in code.--**The changes won't yet be applied to your project files.** Instead, they'll accumulate in Plandex's sandbox.+Plandex will make a plan for your task and then implement that plan in code. **The changes won't yet be applied to your project files.** Instead, they'll accumulate in Plandex's sandbox.## Review The Changes@@ -127,7 +126,7 @@ Once the bad update is rejected, copy the changes from the plan's output or run## Apply The Changes-Once you're happy with the plan's changes, you can apply them to your project files with `plandex apply`:+Once you're happy (enough) with the plan's changes, you can apply them to your project files with `plandex apply`:```bashplandex applydiff --git a/docs/docs/security.md b/docs/docs/security.mdindex 17df316c..b6efa162 100644--- a/docs/docs/security.md+++ b/docs/docs/security.md@@ -1,6 +1,15 @@----sidebar_position: 7+sidebar_position: 9sidebar_label: Security----# Security\ No newline at end of file+# Security+## Ignoring Sensitive Files++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.++## API Key Security++Plandex is a bring-your-own-API-key tool. On the Plandex server, whether that's Plandex Cloud or a self-hosted server, API keys are only stored ephemerally in RAM while they are in active use. They are never written to disk, logged, or stored in a database. As soon as a plan stream ends, the API key is removed from memory and no longer exists anywhere on the Plandex server.++It's also up to you to manage your API keys securely. Try to avoid storing them in multiple places, exposing them to third party services, or sending them around in plain text.\ No newline at end of filediff --git a/docs/docs/self-hosting.md b/docs/docs/self-hosting.mddeleted file mode 100644index 43e50cfe..00000000--- a/docs/docs/self-hosting.md+++ /dev/null@@ -1,6 +0,0 @@-----sidebar_position: 6-sidebar_label: Self-Hosting------# Self-Hosting\ No newline at end of filediff --git a/docs/docusaurus.config.ts b/docs/docusaurus.config.tsindex dd35fe1c..6d4e2438 100644--- a/docs/docusaurus.config.ts+++ b/docs/docusaurus.config.ts@@ -1,8 +1,8 @@import {themes as prismThemes} from 'prism-react-renderer';import type {Config} from '@docusaurus/types';import type * as Preset from '@docusaurus/preset-classic';-import search from "docusaurus-lunr-search"-import redirect from "@docusaurus/plugin-client-redirects"+// import search from "docusaurus-lunr-search"+// import redirect from "@docusaurus/plugin-client-redirects"const config: Config = {title: 'Plandex Docs',@@ -40,10 +40,10 @@ const config: Config = {theme: {customCss: './src/css/custom.css',},+} satisfies Preset.Options,],],-themeConfig: {// Replace with your project's social cardimage: 'img/plandex-social-preview.png',@@ -51,10 +51,13 @@ const config: Config = {defaultMode: "dark",},navbar: {- title: 'Plandex Docs',+ title: '',logo: {alt: 'Plandex Logo',- src: 'img/plandex-logo-thumb.png',+ src: 'img/plandex-logo-light.png',+ srcDark: 'img/plandex-logo-dark.png',+ href: "https://plandex.ai",+ height: "2.7rem",},items: [{@@ -87,15 +90,23 @@ const config: Config = {theme: prismThemes.github,darkTheme: prismThemes.dracula,},++ algolia: {+ // The application ID provided by Algolia+ appId: 'EG57NOYLYX',+ // Public API key: it is safe to commit it+ apiKey: 'a811f8bcdd87a8b3fe7f22a353b968ef',+ indexName: 'plandex',+ }} satisfies Preset.ThemeConfig,- plugins: [- search,- [- '@docusaurus/plugin-client-redirects',- { redirects: [{ from: '/', to: '/intro'}] },- ],- ]+ // plugins: [+ // search,+ // // [+ // // '@docusaurus/plugin-client-redirects',+ // // { redirects: [{ from: '/', to: '/intro'}] },+ // // ],+ // ]};export default config;diff --git a/docs/package-lock.json b/docs/package-lock.jsonindex d6863950..ae5a1e94 100644--- a/docs/package-lock.json+++ b/docs/package-lock.json@@ -11,6 +11,7 @@"@docusaurus/core": "3.4.0","@docusaurus/plugin-client-redirects": "^3.4.0","@docusaurus/preset-classic": "3.4.0",+ "@docusaurus/theme-search-algolia": "^3.4.0","@mdx-js/react": "^3.0.0","clsx": "^2.0.0","docusaurus-lunr-search": "^3.4.0",diff --git a/docs/package.json b/docs/package.jsonindex b465550d..c5165968 100644--- a/docs/package.json+++ b/docs/package.json@@ -18,6 +18,7 @@"@docusaurus/core": "3.4.0","@docusaurus/plugin-client-redirects": "^3.4.0","@docusaurus/preset-classic": "3.4.0",+ "@docusaurus/theme-search-algolia": "^3.4.0","@mdx-js/react": "^3.0.0","clsx": "^2.0.0","docusaurus-lunr-search": "^3.4.0",diff --git a/docs/src/css/custom.css b/docs/src/css/custom.cssindex 2bc6a4cf..43b99ad2 100644--- a/docs/src/css/custom.css+++ b/docs/src/css/custom.css@@ -28,3 +28,8 @@--ifm-color-primary-lightest: #4fddbf;--docusaurus-highlighted-code-line-bg: rgba(0, 0, 0, 0.3);}++.navbar__logo img {+ height: 145%;+ margin-top: -6px;+}\ No newline at end of filediff --git a/docs/static/_redirects b/docs/static/_redirectsnew file mode 100644index 00000000..9230eeb2--- /dev/null+++ b/docs/static/_redirects@@ -0,0 +1 @@+/ /intro 301!\ No newline at end of filediff --git a/docs/static/img/plandex-logo-dark.png b/docs/static/img/plandex-logo-dark.pngnew file mode 100644index 00000000..d4e834fdBinary files /dev/null and b/docs/static/img/plandex-logo-dark.png differdiff --git a/docs/static/img/plandex-logo-light.png b/docs/static/img/plandex-logo-light.pngnew file mode 100644index 00000000..b0b56a63Binary files /dev/null and b/docs/static/img/plandex-logo-light.png differdiff --git a/guides/ENV_VARS.md b/guides/ENV_VARS.mddeleted file mode 100644index 5fe44b15..00000000--- a/guides/ENV_VARS.md+++ /dev/null@@ -1,43 +0,0 @@--# Environment Variables--Here is a list of all the environment variables (and their defaults) that you can use with `plandex`.--```bash-# --- General -----OPENAI_API_BASE= # Your OpenAI server, such as http://localhost:1234/v1 Defaults to empty.-OPENAI_API_KEY= # Your OpenAI key.--# optional - set api keys for any other providers you're using-export OPENROUTER_API_KEY= # Your OpenRouter.ai API key.-export TOGETHER_API_KEY = # Your Together.ai API key.-# etc.--# --- Plandex specific -----PLANDEX_DATA_DIR= # A directory to put plandex data files (cache etc.) to-PLANDEX_ENV= # Set this to development in order to use custom API host. Defaults to empty.--# Database-PGDATA_DIR=/var/lib/postgresql/data-DATABASE_URL=postgres://<user>:<password>@<host>:<port>/plandex?sslmode=disable-# or-PLANDEX_DB=plandex # Your postgres database.-PLANDEX_USER= # Your postgres user.-PLANDEX_PASSWORD= # Your postgres password.--# --- Development variables (See DEVELOPMENT.md) -----PLANDEX_API_HOST= # Defaults to http://localhost:8080 if PLANDEX_ENV is development, otherwise it is http://api.plandex.ai-PLANDEX_OUT_DIR=/usr/local/bin # The output when using dev.sh--GOENV= # This should be set to development.-GOPATH= # This should be already set to your go folder if you've installed Go lang.--SMTP_HOST= # Youe SMTP host.-SMTP_PORT= # Set this to 1025 e.g. if you are using mailhog.-SMTP_USER= # SMTP username.-SMTP_PASSWORD= # SMTP password.--```\ No newline at end of filediff --git a/guides/HOSTING.md b/guides/HOSTING.mddeleted file mode 100644index 5a32877a..00000000--- a/guides/HOSTING.md+++ /dev/null@@ -1,129 +0,0 @@-# Plandex self-hosting 🏠--## Quick start script ⚡️--```bash-git clone https://github.com/plandex-ai/plandex.git-cd plandex/app-./start_local.sh-```--## Requirements--The Plandex server requires a PostgreSQL database (ideally v14), a persistent file system, git, and these environment variables (if using the docker build command below):--```bash-export DATABASE_URL=postgres://user:password@host:5432/plandex # replace with your own database URL-export GOENV=production-export SMTP_HOST=smtp.example.com-export SMTP_PORT=587-export SMTP_USER=user-export SMTP_PASSWORD=password-export [email protected] # optional, if not set then SMTP_USER is used-```--Or, if you are using the `docker compose` option below, cp `app/_env` to `app/.env` and set the values in that file.--### PostgreSQL Database--A user and database needs to be created in postgres. If you use [docker-compose](#using-docker-compose) this will be done when the postgres container starts. Otherwise:--```sql-CREATE USER 'user' WITH PASSWORD 'password';-CREATE DATABASE 'plandex' OWNER 'user';-GRANT ALL PRIVILEGES ON DATABASE 'plandex' TO 'user';-```--## Using Docker Build--It can be run from a Dockerfile at `app/Dockerfile.server`:--```bash-git clone https://github.com/plandex-ai/plandex.git-VERSION=$(cat app/server/version.txt) # or use the version you want-git checkout server/v$VERSION-cd plandex/app-mkdir ~/plandex-server # or another directory where you want to store files-docker build -t plandex-server -f Dockerfile.server .-docker run -p 8080:8080 \- -v ~/plandex-server:/plandex-server \- -e DATABASE_URL \- -e GOENV \- -e SMTP_HOST \- -e SMTP_PORT \- -e SMTP_USER \- -e SMTP_PASSWORD \- plandex-server-```--## Using Docker Compose--If you don't have, or don't want to spend the time to setup a PostgreSQL server, you can use the `docker-compose.yml` file.--```bash-cd plandex/app-cp _env .env-# edit .env to set the required environment variables for postgres-docker compose build-docker compose up-```--## Run From Source--Or you can run it from source:--```bash-git clone https://github.com/plandex-ai/plandex.git-cd plandex/-VERSION=$(cat app/server/version.txt) # or use the version you want-git checkout server/v$VERSION-cd app/server-export PLANDEX_BASE_DIR=~/plandex-server # or another directory where you want to store files-go run main.go-```--## Notes--The server listens on port 8080 by default.--The server requires access to a persistent file system. If you're using Docker, it should be mounted to the container. In production, the `/plandex-server` directory is used by default as the base directory to read and write files. You can use the `PLANDEX_BASE_DIR` environment variable to change this.--In production, authentication emails are sent through SMTP. You can use a service like SendGrid or your own SMTP server.--### Development Mode--If you set `export GOENV=development` instead of `production`:--- Authentication tokens will be copied to the clipboard instead of sent via email, and a system notification will pop up to let you know that the token is ready to paste. (SMTP environment variables are not required in development mode.) The pin will also be output to the console.--- The default base directory will be `$HOME/plandex-server` instead of `/plandex-server`. It can still be overridden with `PLANDEX_BASE_DIR`.--### Health Check--You can check if the server is running by sending a GET request to `/health`. If all is well, it will return a 200 status code.--### Create a New Account--Once the server is running, you can create a new account by running `plandex sign-in` on your local machine.--```bash-plandex sign-in # follow the prompts to create a new account on your self-hosted server-```--### Note: Local CLI Files--If you use the Plandex CLI and then for some reason you reset the database or use a new one, you'll need to remove the local files that the CLI creates in directories where you used Plandex in order to start fresh. Otherwise, the CLI will with an account that doesn't exist in the new database and you'll get errors. This could also happen if you use Plandex Cloud and then switch to self-hosting.--To resolve this, remove the following in any directory you used the CLI in:--- `.plandex-dev` directory if you ran the CLI with `PLANDEX_ENV=development`-- `.plandex` directory otherwise--Then run `plandex sign-in` again to create a new account.--If you're still having trouble with accounts, you can also remove the following from your $HOME directory to fully reset them:--- `.plandex-home-dev` directory if you ran the CLI with `PLANDEX_ENV=development`-- `.plandex-home` directory otherwise--diff --git a/guides/SECURITY.md b/guides/SECURITY.mddeleted file mode 100644index 86612521..00000000--- a/guides/SECURITY.md+++ /dev/null@@ -1,21 +0,0 @@-# Plandex security 🔐--Plandex Cloud follows best practices for network and data security. As I (Plandex's creator 👋) am also the founder of a devops-security company ([EnvKey](https://envkey.com)), this is an area I have experience in and take extremely seriously. Data is encrypted in transit and at rest. The database runs within a private, hardened network.--## Ignores sensitive files--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.--## API key security--Plandex is a bring-your-own-API-key tool. On the Plandex server, whether that's Plandex Cloud or a self-hosted server, API keys are only stored ephemerally in RAM while they are in active use. They are never written to disk, logged, or stored in a database. As soon as a plan stream ends, the API key is removed from memory and no longer exists anywhere on our servers.--It's also up to you to manage your API keys securely. Try to avoid storing them in multiple places, exposing them to third party services, or sending them around in plain text. If you'd like some help, please do check out the aforementioned [EnvKey](https://envkey.com) for secrets management. It's open source, end-to-end encrypted, easy to use, and free for up to 3 users. To set your `OPENAI_API_KEY` with EnvKey, you'd add it to an app in the EnvKey UI or CLI, then run `eval $(envkey-source)` in your terminal.--## Third party services--- Plandex Cloud relies on AWS for all database and hosting services.-- [EnvKey](https://envkey.com) for configuration and secrets management (only used in development so far).-- Github for code storage.-- OpenAI (called on your behalf) for AI models (other model providers will be added in the future).-- See the [privacy overview](PRIVACY.md) for more details on third parties and data retention.diff --git a/guides/USAGE.md b/guides/USAGE.mddeleted file mode 100644index b666753f..00000000--- a/guides/USAGE.md+++ /dev/null@@ -1,372 +0,0 @@-# Using Plandex 🛠️--## Provider API key(s) 🔑--By default, Plandex uses the OpenAI API. While you can use Plandex with many different providers and models, Plandex requires reliable function calling, which can still be a challenge to find in non-OpenAI models. For getting started, it's recommended to begin with OpenAI.--If you don't have an OpenAI account, first [sign up here.](https://platform.openai.com/signup)--Then [generate an API key here.](https://platform.openai.com/account/api-keys)--You'll also need API keys for any other providers you plan on using, like OpenRouter.ai (Anthropic, Gemini, and open source models), Together.ai (open source models), Replicate, Ollama, and more.--## Environment variables 💻--```bash-export OPENAI_API_KEY=...--export OPENAI_API_BASE=... # optional - set a different base url for OpenAI calls e.g. https://<your-proxy>/v1-export OPENAI_ORG_ID=... # optional - set the OpenAI OrgID if you have multiple orgs--# optional - set api keys for any other providers you're using-export OPENROUTER_API_KEY=...-export TOGETHER_API_KEY...-```--## New 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.--```bash-cd your-project-dir-```--Then **start your first plan** with `plandex new`.--```bash-plandex new-```--When you create a plan, Plandex will automatically name your plan after you give it a task, but you can also give it a name up front.--```bash-plandex new -n foo-adapters-component-```--If you don't give your plan a name up front, it will be named 'draft' until you give it a task. 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.--## Loading context 📄--After creating a plan, load any relevant files, images, directories, directory layouts, urls, or other data into the plan context.--```bash-plandex load component.ts action.ts reducer.ts-plandex load lib -r # loads lib and all its subdirectories-plandex load * # loads all files in the current directory-plandex load * -r # loads all files in the current directory and all sub directories-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 (GPT-4o only so far)-```--For loading images, png, jpeg, non-animated gif, and webp formats are supported. So far, this feature is only available with the default OpenAI GPT-4o model.--## Tasks ⚡️--Now give the AI a task to do.--```bash-# with no arguments, vim or nano will open and you can type your task there-plandex tell-# you can pass a task directly as a string-# press enter for line breaks while inside the quotes-plandex tell 'build another component like this one that displays foo adapters in the table rather than bar adapters.-quote> use the same layout and styles, but update the column headers and formatting to match the new data.-quote> add the needed reducer and action as well. write tests for the new code.'-# load a task from a file-plandex tell --file task.txt # or -f task.txt-```--## Changes 🏗️--Plandex will stream the response to your terminal and build up a set of changes along the way. It will continue as long as necessary and create or update as many files as needed to complete the task. You can stop it at any time if it starts going in the wrong direction or if feedback would be helpful.--You can review the changes that Plandex has built up so far in a user-friendly TUI changes viewer.--```bash-plandex changes-```--If you're happy with the changes, apply them to your files.--```bash-plandex apply-```--If you're in a git repo, Plandex will automatically add a commit with a nicely formatted message describing the changes. Any uncommitted changes that were present in your working directory beforehand will be unaffected.--## Rewind ⏪--If you want to rewind and try a different approach, you can use `log` to show a list of updates and `rewind` commands to go back in time.--```bash-plandex log # show a list of all updates to the plan, including prompts, replies, and builds-plandex rewind # go back a single step-plandex rewind 3 # go back 3 steps-plandex rewind a7c8d66 # rewind to a specific state-```--## Branches 🌱--If you want to try a different approach but also keep the current one around, you can use branches. Create a new branch before rewinding.--```bash-plandex checkout new-approach # create a new branch and switch to it-plandex rewind 2-plandex tell 'write the tests before the components.'-plandex branches # see all branches-plandex delete-branch new-approach # delete a branch-```--## Continue ▶️--If a plan has stopped and you just want to continue where you left off, you can use the `continue` command.--```bash-plandex continue # continue the current plan-```--## Background tasks 🚞--If you want to run a command in the background, use the --bg flag.--```bash-plandex tell --bg 'now add another similar component for widget adapters'-```--To see plans that are currently running (or recently finished) and their current status, use the `ps` command. You can connect to a running plan's stream to check on it. Or you can stop it.--```bash-plandex ps # show active and recently finished plans-plandex connect # select an active plan to connect to-plandex stop # select an active plan to stop-```--## Context management 📑--You can see the plan's current context with the `ls` command. You can remove context with the `rm` command or clear it all with the `clear` command.--```bash-plandex ls # list all context in current plan-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-plandex clear # remove all context-```--If files in context are modified outside of Plandex, you will be prompted to update them the next time you interact with the AI. You can also update them manually with the `update` command.--```bash-plandex update # update files in context-```--## Plans 🌟--When you have multiple plans, you can list them with the `plans` command, switch between them with the `cd` command, see the current plan with the `current` command, and delete plans with the `delete-plan` command.--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.--```-plandex plans # list all plans--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--plandex current # show the current 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--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-```--## 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-```--## Model settings 🧠--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 # 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-```--Model changes are versioned and can be rewound or applied to a branch just like any other change.--### Model defaults--`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 # 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--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-```--### 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 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-```--## .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** in Plandex (see next section).--## Orgs 👥--When creating a new org, you have the option of automatically granting access to anyone with an email address on your domain. If you choose not to do this, or you want to invite someone from outside your email domain, you can use `plandex invite`.--To join an org you've been invited to, use `plandex sign-in`.--To list users and pending invites, use `plandex users`.--To revoke an invite or remove a user, use `plandex revoke`.--Orgs will be the basis for plan sharing and collaboration in future releases.--## 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.--<!-- ```bash-cd your-project-plandex new -n root-project-plan # cwd is 'your-project'-plandex current # 'your-project' current plan is root-project-plan-plandex load file.go # loads 'your-project/file.go'-cd some-subdirectory # cwd is now 'some-subdirectory'-plandex new -n subdir-plan1 # current plan is subdir-plan1-plandex load subfile.go # loads 'some-subdirectory/subfile.go'-plandex new -n subdir-plan2 # current plan is now subdir-plan2-plandex plans # shows subdir-plan1 and subdir-plan2 in current directory + root-project-plan in parent directory-cd ../ # cwd is now 'your-project', current plan is root-project-plan-plandex plans # shows root-project-plan in current directory + subdir-plan1 and subdir-plan2 in child directory 'some-subdirectory'-cd some-subdirectory # cwd is now 'some-subdirectory', current plan is subdir-plan2-plandex cd subdir-plan1 # cwd is still 'some-subdirectory', current plan is now subdir-plan1-``` -->--One more thing to note on directories: 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-```--## Ignoring files 🙈--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.--## Help ℹ️--There are a few more commands that haven't been covered in this guide. To see all available commands:--```-plandex help-```--For help on any command:--```-plandex [command] --help-```--## Aliases 🥷--You can use the `pdx` alias anywhere you would use `plandex`. Many commands have short aliases as well.--```bash-pdx l component.ts action.ts reducer.ts # plandex load-pdx t -f task.txt # plandex tell-pdx co # plandex checkout-pdx br # plandex branches-pdx rw # plandex rewind-pdx c # plandex continue-pdx ch # plandex changes-pdx ap # plandex apply-pdx conn # plandex connect-pdx s # plandex stop-pdx pl # plandex plans-pdx cu # plandex current-pdx dp # plandex delete-plan-pdx db # plandex delete-branch-```