Plandex

Orchestrates AI-driven coding tasks through a structured 4-phase workflow: chat for exploration, tell for task description, build for converting AI responses into file modifications, and apply for writing changes to disk. Each phase maintains plan state in a server-side database, enabling resumable execution and rollback capabilities. The system uses a sandbox environment to stage changes separately from project files until explicit application.

Builds semantic understanding of codebases up to 20M+ tokens by using tree-sitter to generate project maps containing function signatures, type definitions, and structural relationships without loading full file contents. Supports 2M token effective context window with intelligent context caching to reduce API costs and latency. Context is categorized by type (files, directories, notes, images, URLs) and managed through explicit load commands that track token consumption.

Implements user authentication through API keys for programmatic access and session-based authentication for CLI clients. Supports multi-user deployments with per-user plan isolation and access control. API keys are stored securely with hashing and can be revoked or rotated without affecting other users.

Implements comprehensive error handling across the plan execution pipeline with structured logging for debugging and monitoring. Errors are categorized by type (API errors, validation errors, file system errors) and propagated with context through the execution chain. Structured logs include timestamps, execution phase, model information, and error details, enabling root cause analysis and performance monitoring.

Tracks token consumption per plan execution with model-specific accounting for input, output, and cached tokens. Provides cost estimation based on model pricing and actual token usage, enabling budget tracking and cost optimization. Token counts are displayed in real-time during plan execution and stored in plan history for analysis.

Assigns specialized AI models to different development roles (planner, implementer, builder, etc.) through configurable model packs, enabling task-specific optimization. Each role can use different models (Claude, GPT-4, Ollama, etc.) based on the task requirements. Model configuration is persisted per plan, allowing fine-grained control over which models handle planning, implementation, and code generation phases.

Converts AI-generated responses into structured file modifications through a multi-stage pipeline: parsing AI output into modification instructions, validating changes against project structure, generating diffs, and staging modifications in a sandbox before application. Uses language-specific AST parsing to ensure syntactically correct code generation and enable structural-aware edits (e.g., inserting methods into classes, adding imports).

Provides a terminal-based REPL interface that streams AI responses, plan execution status, and file modifications in real-time with interactive controls. Uses server-sent events (SSE) or WebSocket streaming to push updates to the CLI client, enabling live progress tracking without polling. The UI displays token consumption, model selection, and execution phase transitions as they occur.

Manages concurrent plan execution through repository-level locking and per-plan sandboxes, preventing conflicting file modifications when multiple plans operate on the same codebase. Each plan maintains its own sandbox environment with staged changes, and the system enforces exclusive locks during the apply phase to ensure atomic writes. Git integration tracks plan-specific commits and enables rollback to pre-plan states.

Provides AI-powered code completion that understands full codebase context through indexed project maps and loaded file content. Completion suggestions are generated by AI models with access to project structure, type definitions, and relevant code snippets, enabling context-aware recommendations that respect project conventions and patterns. Completion is integrated into the plan execution workflow, triggered during the tell and build phases.

Exposes a REST API for programmatic access to plan execution, context management, and model configuration. Supports streaming responses for long-running operations (plan execution, AI responses) using chunked transfer encoding or Server-Sent Events. The API uses JSON request/response bodies with standardized error handling and supports both synchronous and asynchronous operation modes.

Stores all plan state, execution history, and context metadata in a persistent database (SQLite for local mode, PostgreSQL for cloud/self-hosted). Implements schema versioning through migrations, enabling safe schema evolution across Plandex versions. Plan state includes chat history, file modifications, model configuration, and execution logs, all queryable for audit and debugging purposes.

Enables self-hosted Plandex deployment with support for local AI models via Ollama, eliminating dependency on cloud APIs for sensitive code. Provides Docker containerization for easy deployment and configuration management through environment variables. Local mode uses SQLite for data storage and supports all plan execution features without external API calls.