How plandex-ai/plandex works
Project Type and Purpose
• This is a full-stack, terminal-based AI agent split into two main processes:
a. A CLI client (app/cli) used by developers to interact via REPL or commands.
b. A Server (app/server) providing HTTP/gRPC APIs, state management, database persistence, syntax parsing, and integration with AI model providers.
Main Components
• CLI Client
• REPL / command parser / UI (TUI)
• Local cache and file-map modules
• Server API
• HTTP/gRPC endpoint layer (handlers, routes)
• Domain logic (plans, contexts, streams)
• Syntax & file-map service (tree-sitter)
• AI orchestration (litellm_proxy, batching, streaming)
• Email & notification service
• Shutdown / health check endpoints
• Data Store
• Relational DB (Postgres via app/server/db)
• Migrations
• External Services
• AI Model Providers (OpenAI, Anthropic, Google, OpenRouter, etc.)
• Email SMTP or API
• Git (for file diffs, branch management)
Relationships and Data Flows
• CLI → Server: REST or gRPC calls for all actions (apply, plan, stream, auth, etc.)
• Server → DB: CRUD operations, transactions, queue & locks
• Server → AI Providers: HTTP/HTTPS requests for context loading, prompts, streaming responses
• Server → Syntax Module: Local function calls for project map generation & structured edits
• Server → Email: Outbound notifications (invites, verification)
• Server → Git: File diffs, commit generation, branch operations
• Server → CLI: Server streams back events, logs, diffs, summaries
Key Architectural Patterns
• Separation of Concerns: CLI and Server are distinct processes, communicate over an API.
• Hexagonal Architecture: Handlers → Domain → Adapters (DB, AI providers, syntax).
• Event / Stream Processing: Plans and build executions are streamed to the CLI.
• Plugin-style Model Providers: Shared interfaces for models; concrete implementations in app/shared/ai_models_*.
• Cumulative Diff Sandbox: All file edits are staged until approved, enabling rollbacks.