====== Plandex ======

**Plandex** is an open-source, terminal-based AI coding agent designed for large-scale software development across complex, multi-file codebases.((https://github.com/plandex-ai/plandex|Plandex on GitHub)) It combines autonomous planning, intelligent context discovery, and a sandbox-first workflow to deliver production-grade code changes safely and efficiently.

{{tag>ai_agent cli coding planning open_source}}

| **Repository** | [[https://github.com/plandex-ai/plandex]] |
| **Website** | [[https://plandex.ai]] |
| **Language** | Go |
| **License** | Open Source |
| **Stars** | 14,000+ |
| **Creator** | Dane (Plandex) |

===== Overview =====

Plandex is built for developers who need AI assistance on real-world projects with large codebases. Unlike simpler AI coding assistants, Plandex can autonomously handle tasks spanning dozens of files, supporting projects with 20M+ tokens and codebases with millions of lines.((https://docs.plandex.ai|Documentation)) It uses a unique plan/apply workflow where all changes accumulate in a version-controlled sandbox before being applied to the project.

===== Key Features =====

  * **Full Auto Mode** -- Completes complex tasks autonomously including planning, context loading, implementation, command execution, and auto-debugging
  * **Multi-File Operations** -- Updates dozens of files in a single task without manual intervention
  * **Diff Review Sandbox** -- All changes accumulate in a version-controlled sandbox before approval
  * **Sandbox Versioning** -- Rewind to any previous state or create branches for alternative approaches
  * **2M Token Context Window** -- Indexes projects of 20M+ tokens using tree-sitter project maps across 30+ languages
  * **Configurable Autonomy** -- Move between full automation and step-by-step manual control
  * **Multi-Provider LLM Support** -- Combines models from Anthropic, OpenAI, Google, and more((https://plandex.ai|Official Website))

===== Architecture =====

Plandex uses a client-server architecture. The server can be self-hosted locally via Docker or accessed through Plandex Cloud. The plan/apply workflow proceeds through distinct phases:((https://docs.plandex.ai/hosting/self-hosting/local-mode-quickstart|Self-Hosting Guide))

  - **Context Discovery** -- Tree-sitter project maps identify relevant files
  - **Planning** -- AI creates a detailed execution plan
  - **Implementation** -- Each step is executed systematically
  - **Change Application** -- A race orchestration between multiple strategies (deterministic edits, diff edits, whole file builds)
  - **Validation** -- Commands run for dependency installation, builds, and tests
  - **Auto-Debugging** -- Failed commands are automatically debugged

<mermaid>
graph TD
    A[User Prompt] --> B[Context Discovery]
    B --> C[Tree-sitter Project Map]
    C --> D[Planning Phase]
    D --> E[Implementation]
    E --> F{Change Strategy Race}
    F --> G[Deterministic Edits]
    F --> H[Diff Edits]
    F --> I[Whole File Build]
    G --> J[Sandbox]
    H --> J
    I --> J
    J --> K{User Review}
    K -->|Approve| L[Apply to Project]
    K -->|Reject| M[Rewind / Branch]
    L --> N[Run Tests]
    N -->|Fail| O[Auto-Debug]
    O --> E
    N -->|Pass| P[Done]
</mermaid>

===== Supported LLMs =====

Plandex supports a wide range of model providers through built-in integrations and model packs:

  * **Anthropic** -- Claude models
  * **OpenAI** -- GPT and o-series models
  * **Google** -- Gemini 2.5 Pro/Flash via AI Studio and Vertex AI
  * **Azure OpenAI** -- Enterprise deployments
  * **AWS Bedrock** -- Managed model access
  * **DeepSeek** -- DeepSeek API
  * **OpenRouter** -- Aggregated access
  * **Ollama** -- Local open-source models
  * **Perplexity** -- Search-augmented models

Built-in model packs include ''gemini-planner'', ''google'', and ''o3-planner'' for different workflow optimizations.

===== Installation =====

Plandex can be self-hosted locally with Docker or used via Plandex Cloud:((https://docs.plandex.ai/hosting/self-hosting/local-mode-quickstart|Self-Hosting Guide))

<code bash>
# Self-hosted local mode with Docker
docker run plandex/plandex

# Cloud mode - two tiers available:
# 1. Integrated Models (no API keys needed)
# 2. BYO API Key (use your own accounts)
</code>

Configuration is JSON-based with IDE integration support. Model settings (temperature, top-p) are version-controlled, enabling A/B testing across branches.

===== CLI Usage =====

<code bash>
# Configure models for current plan
plandex set-model

# Set default models for new plans
plandex set-model default

# Manage custom providers and model packs
plandex models custom

# JSON editing mode
plandex set-model --json
</code>


===== See Also =====

  * [[openai_codex]] -- OpenAI Codex CLI terminal coding agent
  * [[gptme]] -- Terminal agent with local tools
  * [[claude_code]] -- Anthropic Claude Code CLI agent
  * [[warp_terminal]] -- Warp agentic development environment

===== References =====