How abheytiwari/codi works
1. What this repo is
- Codi is a terminal-based AI coding agent, not a library or web service.
- Its architecture centers on an interactive loop that takes a user request, decides whether tools are needed, executes those tools, validates the result, and retries if necessary.
2. Primary runtime boundary: terminal UI
- The user interacts through codi on the command line.
- cli.py is the package entrypoint, while main.py handles the interactive TUI prompt, commands like /mode, /index, /tools, and output rendering.
- This layer is only orchestration and presentation; it does not contain the agent logic itself.
3. Core agent control flow
- agent.py and the core/ modules implement the main reasoning loop.
- The high-level split is:
- core/planner.py decides whether a request is simple Q&A or requires tool use.
- core/improver.py orchestrates the multi-step task and maintains the iteration loop.
- core/executor.py turns a single step into a structured action bundle.
- core/validator.py judges whether the last round succeeded or needs correction.
- This is a two-LLM design: an orchestrator/refiner model and a stronger coder model.
4. Execution boundary: dispatcher
- dispatcher.py is the central tool router.
- It receives JSON-like tool requests from the executor, runs the requested actions, and returns structured results.
- The dispatcher is the clear boundary between LLM-produced intent and real side effects.
5. Tool system
- tools/registry.py provides the unified catalog of available tools.
- Tools are loaded from two sources:
- local Python functions in tools/local/
- MCP-backed tools in tools/mcp/
- The design keeps the LLM-facing interface uniform even when the underlying capability comes from very different runtimes.
6. Local tools
- tools/local/file_tools.py, search_tools.py, and shell_tools.py expose filesystem, code search, and shell execution capabilities.
- These are the core side-effecting primitives for editing codebases and inspecting projects.
- They are intentionally simple callable functions, which makes them easy to register and invoke from the dispatcher.
7. MCP integration
- mcp_manager.py, mcp_client.py, and mcp/mcp_tools.py integrate Model Context Protocol servers.
- mcp_servers.json defines which servers are enabled and how they are configured.
- This layer extends Codi with external capabilities such as filesystem, git, GitHub, browser automation, databases, search, and other services without hard-wiring them into the core agent.
8. State, memory, and context control
- state/temp_db.py defines the per-run RunState, which holds iteration count, step outputs, and other session-scoped data.
- memory.py stores conversation history and supports compression so sessions can continue across multiple turns.
- context_trimmer.py is the budget guardrail that keeps prompts within token limits by trimming or summarizing context before LLM calls.
9. Project indexing and retrieval
- indexer.py builds and queries a local vector index for the current working directory.
- The README indicates this uses a local vector database, with CODI_CHROMA_DIR pointing to the per-project storage location.
- This subsystem feeds the improver with codebase context before planning or execution begins.
10. LLM provider abstraction
- llm_factory.py hides the differences between local, cloud, hybrid, and Air LLM modes.
- config.py controls which provider and models are active, while config_loader.py pulls secrets from environment variables or .env.
- The architecture is designed so the rest of the system talks to a common LLM interface, regardless of whether the backend is Ollama, Groq, Anthropic, OpenAI, Gemini, or Air LLM.
11. Logging, diagnostics, and observability
- logger.py writes structured JSON events to codi.log.
- log_viewer.py powers the live /logs telemetry view, showing tool calls, LLM decisions, and failures.
- This is important for debugging because the agent loop is iterative and can fail in multiple places.
12. Packaging and repo shape
- The repository contains both top-level modules and mirrored package directories like core/, tools/, and state/.
- The duplicated names such as planner.py, executor.py, and validator.py at the root likely serve compatibility or thin-wrapper purposes around the structured package layout.
- pyproject.toml and requirements.txt define the Python package/runtime, while index.html and test files are ancillary and not part of the main control flow.
13. End-to-end data flow
- The typical path is: user prompt → planner → improver context gathering/index lookup → executor emits tool JSON → dispatcher runs local/MCP tools → results stored in run state → validator approves or rejects → improver retries or summarizes.
- The key architectural boundary is that LLMs do not directly perform actions; they only produce structured instructions that the dispatcher and tool registry execute.
14. External dependencies that matter architecturally
- Ollama is the main local model runtime.
- Cloud providers supported are Groq, Anthropic, OpenAI, and Gemini.
- MCP servers introduce optional integrations with GitHub, filesystem, databases, browsers, search engines, and developer tooling.
- These integrations are optional plugins around a stable core loop, not core dependencies of the agent itself.
Main entry points: improver.py Improver · main.py TUI loop · agent.py Agent · planner.py Planner
Components 21
Terminal runtime
Command-line entrypoint, prompt loop, and user-facing commands.
Agent loop
Planning, execution, validation, and retry orchestration.
- Agent · Top-level agent coordination surface.
agent.py - Planner · Classifies requests and decides whether tools are needed.
core/planner.py - Improver · Runs the multi-step task loop and retries when needed.
core/improver.py - Executor · Turns a step into structured tool actions.
core/executor.py - Validator · Evaluates whether the latest round succeeded or needs correction.
core/validator.py
Tooling
Unified tool catalog plus local and MCP-backed capabilities.
- Dispatcher · Executes structured tool requests and returns results.
dispatcher.py - Tool registry · Unified catalog of available tools.
tools/registry.py - Local tools · Filesystem, code search, and shell execution primitives.
tools/local - MCP tools · MCP-backed tool adapters exposed through the same interface.
tools/mcp/mcp_tools.py - MCP manager · Loads and coordinates configured MCP servers.
mcp_manager.py - MCP client · Connects to MCP servers and exchanges tool messages.
mcp_client.py
Context
State, memory, trimming, and codebase retrieval.
- Run state · Per-run iteration data and step outputs.
state/temp_db.py - Memory · Conversation history and compression across turns.
memory.py - Context trimmer · Trims or summarizes context to fit token limits.
context_trimmer.py - Indexer · Builds and queries the local codebase index.
indexer.py
Provider and observability
LLM abstraction, config, logging, and diagnostics.
- LLM factory · Unifies local and cloud model backends behind one interface.
llm_factory.py - Config · Selects providers, models, and runtime behavior.
config.py - Logger · Writes structured events to codi.log.
logger.py - Log viewer · Live view of tool calls, decisions, and failures.
log_viewer.py
Connections 25
- CLI entry → TUI loop: launches · CLI entry starts the terminal interaction loop.
- TUI loop → Agent: submits prompt · User requests are handed to the agent orchestration layer.
- Agent → Planner: routes request · Agent delegates initial classification and planning.
- Planner → Improver: needs tools · Tool-using tasks are sent into the iterative improver loop.
- Planner → LLM factory: uses model · Planning relies on the configured LLM backend.
- Improver → Indexer: gathers context · Retrieval augments the task with codebase context.
- Improver → Context trimmer: fits budget · Context is reduced before model calls when needed.
- Improver → Executor: creates step · Each iteration produces a structured execution step.
- Executor → LLM factory: asks coder model · Executor uses the model abstraction to synthesize actions.
- Executor → Dispatcher: emits actions · Structured tool instructions are sent to the dispatcher.
- Dispatcher → Tool registry: resolves tool · Dispatcher looks up tool implementations in the catalog.
- Tool registry → Local tools: includes · Local callable tools are registered in the unified catalog.
- Tool registry → MCP tools: includes · MCP-backed tools are registered in the unified catalog.
- MCP tools → MCP manager: loads servers · MCP tool adapters depend on configured servers.
- MCP manager → MCP client: connects · Server coordination is mediated through the MCP client.
- Dispatcher → Run state: records result · Tool outputs and iteration data are stored in run state.
- Improver → Validator: checks outcome · Validator decides whether to retry or finalize.
- Validator → Run state: reads state · Validation uses the accumulated run state.
- Improver → Memory: updates history · Conversation history is persisted across turns.
- Memory → Context trimmer: compressed by · Long histories are compressed or trimmed for prompts.
- TUI loop → Log viewer: opens logs · Terminal commands can surface live telemetry views.
- Agent → Logger: emits events · Agent activity is written as structured logs.
- LLM factory → Config: reads config · Provider selection and model settings come from configuration.
- TUI loop → Config: reads settings · UI behavior depends on runtime configuration.
- Log viewer → Logger: reads logs · The viewer presents the structured event stream.