plandex

Plandex breaks down large coding tasks into sequential plans that progress through distinct lifecycle phases (chat, tell, continue, build, apply). Each phase uses specialized AI models to discuss requirements, describe implementation tasks, execute code generation, and apply changes to the repository. The system maintains plan state in a persistent database and streams responses through a terminal UI, allowing developers to iteratively refine plans before committing changes.

Plandex indexes project directories using tree-sitter AST parsing to generate semantic project maps that represent file structure, function signatures, and type definitions without loading full file contents. This enables projects with 20M+ tokens of indexable content to fit within a 2M token effective context window. The system uses context caching to reduce API costs and latency, and developers can selectively load files, directories, or tree-only views to control token usage.

Plandex abstracts multiple LLM providers (OpenAI, Anthropic, Ollama) behind a unified interface, enabling developers to switch providers without changing plan logic. The system implements provider-specific adapters that handle API differences (function calling syntax, streaming, context windows) and normalize responses into a common format. Function calling is supported across all providers through a schema-based registry that maps tool definitions to provider-specific formats.

Plandex persists plan state, execution history, and context metadata in a relational database (SQLite, PostgreSQL) using a migration-based schema management system. The database tracks plan lifecycle events, stores file modifications, maintains context caching metadata, and enables plan resumption after server restarts. Schema migrations are versioned and applied automatically on server startup, ensuring compatibility across releases.

Plandex integrates with git to track plan-generated changes, detect conflicts with concurrent modifications, and apply merge strategies when necessary. The system checks for uncommitted changes before applying plans, detects conflicts between plan modifications and repository state, and provides options for conflict resolution (abort, merge, overwrite). Git history is preserved through explicit commits, and plans can be reverted by reversing commits.

Plandex assigns specialized AI models to different development roles (planner, builder, verifier) through configurable model packs. Developers can define which model handles planning tasks, code generation, and verification, allowing optimization for cost, speed, or quality. The system supports multiple LLM providers (OpenAI, Anthropic, Ollama) and enables switching between models without changing plan logic.

Plandex maintains AI-generated code changes in a sandbox environment separate from the actual project files until explicitly applied. The system uses git to track modifications, enabling developers to review diffs, revert changes, and apply modifications selectively. The build phase converts plan responses into file modifications stored in the sandbox, and the apply phase writes changes to the repository with full git integration for commit tracking.

Plandex renders plan execution progress through a streaming terminal UI that displays AI responses, token usage, model assignments, and phase transitions in real-time. The UI uses Go's terminal rendering libraries to create interactive displays that update as the server streams responses, providing developers with immediate feedback on plan execution status without polling.

Plandex generates code across 40+ programming languages supported by tree-sitter, with language detection and syntax-aware modification handling. The system uses language-specific AST parsing to understand code structure and generate modifications that respect language conventions. Plans are language-agnostic — a single plan can generate code in Python, Go, JavaScript, and other languages within the same project.

Plandex exposes a REST HTTP API that handles plan creation, execution, context management, and model configuration. The API supports streaming responses for long-running operations (plan execution, code generation) and persists plan state in a database, enabling clients to reconnect and resume interrupted operations. The server maintains active plan locks to prevent concurrent modifications and uses a request handler pattern to route API calls to appropriate business logic.

Plandex maintains a single active plan per repository and uses file-based or database-backed locking to prevent concurrent modifications. The system tracks active plan state, enforces exclusive access during build and apply phases, and prevents multiple clients from executing plans simultaneously on the same repository. Lock acquisition is checked before each plan operation and released after completion or timeout.

Plandex tracks token usage across context loading, plan execution, and model responses, providing developers with real-time token counts and cost estimates. The system implements context caching to reduce token consumption on repeated requests and allows developers to set token budgets per plan. Token counting is performed before API calls to prevent unexpected overages, and the system provides detailed breakdowns of token usage by context type (files, directories, images, notes).

Plandex provides a REPL (Read-Eval-Print Loop) interface where developers can interactively execute commands (chat, tell, continue, build, apply) within a single plan context. The REPL maintains command history, allows editing previous commands, and preserves plan state across multiple commands. Developers can iterate on plans without exiting and re-entering the tool, enabling rapid experimentation and refinement.