DOCSEARCHbyAlgolia
Submit Docs

Plandex

repository·main·Indexed 12 days ago

https://github.com/plandex-ai/plandex

A terminal-based AI coding agent designed to plan and execute large-scale coding tasks across multiple files. It features smart context management, a cumulative diff review sandbox, and supports various LLM providers via self-hosted or local modes.

Tokens
105K
Snippets
384
Records
533
Agent score
94%

What's inside Plandex

  1. What is a Plandex Plan?

    main

    A plan is the core unit of work in Plandex, similar to a conversation in ChatGPT or Claude. It encapsulates the entire state of a specific task or feature development.

    A plan consists of:

    • Context: Any files or information loaded by you or the model.
    • Conversation: The history of prompts and model responses.
    • Pending Changes: Accumulated file modifications that have not yet been finalized.

    Plans support version control and branching, allowing you to manage complex development workflows.

  2. Understand Plandex hosting options

    main

    Plandex offers different hosting models depending on your needs:

    • Self-hosted/Local Mode: Run Plandex locally using Docker or on your own server. This requires you to provide your own API keys (e.g., from OpenRouter.ai or other providers). Follow the local-mode quickstart for setup.
    • Plandex Cloud: (Note: As of 10/3/2025, Plandex Cloud is winding down and no longer accepting new users).

  4. Understand Plandex Context Management

    main

    Context in Plandex consists of files, directories, URLs, images, notes, or piped data that the LLM uses to understand your project. Context is always associated with a plan. Changes to context are version controlled and can be branched.

    Automatic vs. Manual Context

    Automatic Context (Default in v2): When a new plan is created, Plandex generates a project map. The LLM uses this map to select relevant context before planning or responding.

    Manual Context: Useful for minimizing costs, increasing focus, or when you know specific files are required. You can switch to manual mode by:

    • Setting a lower autonomy level (e.g., plus or basic) using plandex set-auto.
    • Starting a REPL or plan with --plus or --basic flags.
    • Setting the auto-load-context config option to false.

    Autonomy Levels and Context Features

    Autonomy Levelauto-load-contextsmart-contextauto-update-context
    none❌❌❌
    basic❌❌❌
    plus❌✅✅
    semi✅✅✅
    full✅✅✅

  5. Advanced role configuration and fallbacks

    main

    When a role is defined as an object instead of a string, you can specify fine-grained parameters and fallback behaviors. This is useful for ensuring plan stability when encountering context limits or API errors.

    Role Config Object Properties:

    • modelId (required): The ID of the model to use.
    • temperature: Controls randomness (0-2).
    • topP: Alternative randomness control (0-1).
    • largeContextFallback: Model to use when the context window is exceeded.
    • largeOutputFallback: Model to use when the required output size is large.
    • errorFallback: Model to use if the primary model fails (e.g., due to an API error).
    • strongModel: A more capable model for complex tasks.
    {
  "$schema": "https://plandex.ai/schemas/model-pack-inline.schema.json",
  "planner": {
    "modelId": "anthropic/claude-opus-4",
    "temperature": 0.7,
    "topP": 0.9,
    "largeContextFallback": "google/gemini-2.5-pro"
  },
  "coder": "anthropic/claude-sonnet-4",
  "architect": "anthropic/claude-sonnet-4",
  "summarizer": "anthropic/claude-3.5-haiku",
  "builder": {
    "modelId": "anthropic/claude-sonnet-4",
    "errorFallback": "openai/gpt-4.1"
  },
  "wholeFileBuilder": {
    "modelId": "anthropic/claude-sonnet-4",
    "largeContextFallback": {
      "modelId": "google/gemini-2.5-pro",
      "largeOutputFallback": "openai/o4-mini-low"
    }
  },
  "names": "anthropic/claude-3.5-haiku",
  "commitMessages": "anthropic/claude-3.5-haiku",
  "autoContinue": "anthropic/claude-3.5-haiku"
}

  7. How Orgs and collaboration work in Plandex

    main

    In Plandex, Orgs (Organizations) are the fundamental unit for collaboration and team management. They solve the problem of multiple users working on the same project.

    Because Plandex generates a .plandex file containing non-sensitive configuration data in project directories, multiple users working in the same repository without an Org will overwrite each other's .plandex files on every push. To avoid this, you should either:

    1. Add all collaborators to the same Org.
    2. Add .plandex to your .gitignore file.

  9. Understand support levels for custom configurations

    main

    The ability to use custom configurations depends on your Plandex deployment:

    • Self-hosted: Full support for custom models, providers, and model packs.
    • Cloud with BYO API Keys: Supports custom models and model packs. However, models can only use built-in providers.
    • Cloud with Integrated Models: Supports custom model packs only. Model packs can only use built-in models.

  10. How execution and debugging behavior relates to autonomy levels

    main

    Plandex's execution and debugging capabilities are governed by your configured autonomy level. The following matrix describes how can-exec, auto-exec, and auto-debug behave across different settings:

    SettingNoneBasicPlusSemiFull
    can-exec❌❌✅✅✅
    auto-exec❌❌❌❌✅
    auto-debug❌❌❌❌✅
    • Full Autonomy: Commands are automatically executed and debugged after changes are applied.
    • Other Levels: You will be prompted to approve execution and debugging steps.

  11. Configure Providers and API Keys

    main

    How you manage providers depends on your hosting mode:

    1. Plandex Cloud (Integrated Models Mode): You use Plandex credits. No provider accounts or API keys are required.
    2. Plandex Cloud (BYO API Key Mode) or Self-Hosted: You must provide your own API keys for the providers you wish to use (e.g., Anthropic, OpenAI, Google).
    3. Custom Providers: If self-hosting, you can use any OpenAI-compatible provider.
    4. Local Models: Plandex supports local execution via Ollama.

  12. Choose a Plandex Cloud billing mode

    main

    Plandex Cloud offers two ways to pay for AI model usage. Note that Plandex Cloud is winding down as of 10/3/2025 and is no longer accepting new users.

    Integrated Models

    • Mechanism: Use Plandex credits to pay for AI models directly.
    • Setup: No separate accounts or API keys required.
    • Pricing: Credits are deducted at the model's price plus a small markup. Includes a $10 trial. Paid plans are $45/month (includes $20 in monthly credits).
    • Best for: Users who want a seamless experience without managing multiple provider accounts.

    BYO API Key (Bring Your Own API Key)

    • Mechanism: Use your own accounts and API keys from model providers.
    • Setup: Requires configuring your own provider keys.
    • Pricing: Free trial available (up to 10 plans and 20 model responses per plan). Paid plans are $30/month.
    • Best for: Users who want to use their existing provider credits and maintain direct control over their API usage.