# abheytiwari/codi architecture

> Architecture diagram of the GitHub repository abheytiwari/codi, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-15). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/abheytiwari/codi
- Repository: https://github.com/abheytiwari/codi

## Overview

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: [`core/improver.py`](https://github.com/abheytiwari/codi/blob/main/core/improver.py) (Improver), [`main.py`](https://github.com/abheytiwari/codi/blob/main/main.py) (TUI loop), [`agent.py`](https://github.com/abheytiwari/codi/blob/main/agent.py) (Agent), [`core/planner.py`](https://github.com/abheytiwari/codi/blob/main/core/planner.py) (Planner)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Terminal runtime"]
  node_cli["CLI entry<br/>entrypoint<br/>[cli.py]"]
  node_main["TUI loop<br/>terminal-ui<br/>[main.py]"]
end

subgraph group_agent["Agent loop"]
  node_agent_py["Agent<br/>orchestrator<br/>[agent.py]"]
  node_planner["Planner<br/>decision<br/>[planner.py]"]
  node_improver["Improver<br/>loop<br/>[improver.py]"]
  node_executor["Executor<br/>action builder<br/>[executor.py]"]
  node_validator["Validator<br/>judge<br/>[validator.py]"]
end

subgraph group_tools["Tooling"]
  node_dispatcher["Dispatcher<br/>tool router<br/>[dispatcher.py]"]
  node_registry["Tool registry<br/>catalog<br/>[registry.py]"]
  node_local_tools["Local tools<br/>filesystem/shell/search"]
  node_mcp_tools["MCP tools<br/>external tools<br/>[mcp_tools.py]"]
  node_mcp_manager["MCP manager<br/>integration<br/>[mcp_manager.py]"]
  node_mcp_client["MCP client<br/>protocol client<br/>[mcp_client.py]"]
end

subgraph group_context["Context"]
  node_state_db[("Run state<br/>session state<br/>[temp_db.py]")]
  node_memory[("Memory<br/>history store<br/>[memory.py]")]
  node_trimmer["Context trimmer<br/>budget guard<br/>[context_trimmer.py]"]
  node_indexer[("Indexer<br/>retrieval<br/>[indexer.py]")]
end

subgraph group_infra["Provider and observability"]
  node_llm_factory["LLM factory<br/>provider abstraction<br/>[llm_factory.py]"]
  node_config["Config<br/>[config.py]"]
  node_logger["Logger<br/>structured logging<br/>[logger.py]"]
  node_log_viewer["Log viewer<br/>telemetry UI<br/>[log_viewer.py]"]
end

node_cli -->|"launches"| node_main
node_main -->|"submits prompt"| node_agent_py
node_agent_py -->|"routes request"| node_planner
node_planner -->|"needs tools"| node_improver
node_planner -->|"uses model"| node_llm_factory
node_improver -->|"gathers context"| node_indexer
node_improver -->|"fits budget"| node_trimmer
node_improver -->|"creates step"| node_executor
node_executor -->|"asks coder model"| node_llm_factory
node_executor -->|"emits actions"| node_dispatcher
node_dispatcher -->|"resolves tool"| node_registry
node_registry -->|"includes"| node_local_tools
node_registry -->|"includes"| node_mcp_tools
node_mcp_tools -->|"loads servers"| node_mcp_manager
node_mcp_manager -->|"connects"| node_mcp_client
node_dispatcher -->|"records result"| node_state_db
node_improver -->|"checks outcome"| node_validator
node_validator -->|"reads state"| node_state_db
node_improver -->|"updates history"| node_memory
node_memory -->|"compressed by"| node_trimmer
node_main -->|"opens logs"| node_log_viewer
node_agent_py -->|"emits events"| node_logger
node_llm_factory -->|"reads config"| node_config
node_main -->|"reads settings"| node_config
node_log_viewer -->|"reads logs"| node_logger

click node_cli "https://github.com/abheytiwari/codi/blob/main/cli.py"
click node_main "https://github.com/abheytiwari/codi/blob/main/main.py"
click node_agent_py "https://github.com/abheytiwari/codi/blob/main/agent.py"
click node_planner "https://github.com/abheytiwari/codi/blob/main/core/planner.py"
click node_improver "https://github.com/abheytiwari/codi/blob/main/core/improver.py"
click node_executor "https://github.com/abheytiwari/codi/blob/main/core/executor.py"
click node_validator "https://github.com/abheytiwari/codi/blob/main/core/validator.py"
click node_dispatcher "https://github.com/abheytiwari/codi/blob/main/dispatcher.py"
click node_registry "https://github.com/abheytiwari/codi/blob/main/tools/registry.py"
click node_local_tools "https://github.com/abheytiwari/codi/tree/main/tools/local"
click node_mcp_tools "https://github.com/abheytiwari/codi/blob/main/tools/mcp/mcp_tools.py"
click node_mcp_manager "https://github.com/abheytiwari/codi/blob/main/mcp_manager.py"
click node_state_db "https://github.com/abheytiwari/codi/blob/main/state/temp_db.py"
click node_memory "https://github.com/abheytiwari/codi/blob/main/memory.py"
click node_trimmer "https://github.com/abheytiwari/codi/blob/main/context_trimmer.py"
click node_indexer "https://github.com/abheytiwari/codi/blob/main/indexer.py"
click node_llm_factory "https://github.com/abheytiwari/codi/blob/main/llm_factory.py"
click node_config "https://github.com/abheytiwari/codi/blob/main/config.py"
click node_logger "https://github.com/abheytiwari/codi/blob/main/logger.py"
click node_log_viewer "https://github.com/abheytiwari/codi/blob/main/log_viewer.py"
click node_mcp_client "https://github.com/abheytiwari/codi/blob/main/mcp_client.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_main toneBlue
class node_agent_py,node_planner,node_improver,node_executor,node_validator toneAmber
class node_dispatcher,node_registry,node_local_tools,node_mcp_tools,node_mcp_manager,node_mcp_client toneMint
class node_state_db,node_memory,node_trimmer,node_indexer toneRose
class node_llm_factory,node_config,node_logger,node_log_viewer toneIndigo
```

## Components

### Terminal runtime

Command-line entrypoint, prompt loop, and user-facing commands.

- [CLI entry](https://github.com/abheytiwari/codi/blob/main/cli.py): entrypoint · Package entrypoint for the codi command. · `cli.py`
- [TUI loop](https://github.com/abheytiwari/codi/blob/main/main.py): terminal-ui · Interactive prompt, slash commands, and output rendering. · `main.py`

### Agent loop

Planning, execution, validation, and retry orchestration.

- [Agent](https://github.com/abheytiwari/codi/blob/main/agent.py): orchestrator · Top-level agent coordination surface. · `agent.py`
- [Planner](https://github.com/abheytiwari/codi/blob/main/core/planner.py): decision · Classifies requests and decides whether tools are needed. · `core/planner.py`
- [Improver](https://github.com/abheytiwari/codi/blob/main/core/improver.py): loop · Runs the multi-step task loop and retries when needed. · `core/improver.py`
- [Executor](https://github.com/abheytiwari/codi/blob/main/core/executor.py): action builder · Turns a step into structured tool actions. · `core/executor.py`
- [Validator](https://github.com/abheytiwari/codi/blob/main/core/validator.py): judge · Evaluates whether the latest round succeeded or needs correction. · `core/validator.py`

### Tooling

Unified tool catalog plus local and MCP-backed capabilities.

- [Dispatcher](https://github.com/abheytiwari/codi/blob/main/dispatcher.py): tool router · Executes structured tool requests and returns results. · `dispatcher.py`
- [Tool registry](https://github.com/abheytiwari/codi/blob/main/tools/registry.py): catalog · Unified catalog of available tools. · `tools/registry.py`
- [Local tools](https://github.com/abheytiwari/codi/tree/main/tools/local): filesystem/shell/search · Filesystem, code search, and shell execution primitives. · `tools/local`
- [MCP tools](https://github.com/abheytiwari/codi/blob/main/tools/mcp/mcp_tools.py): external tools · MCP-backed tool adapters exposed through the same interface. · `tools/mcp/mcp_tools.py`
- [MCP manager](https://github.com/abheytiwari/codi/blob/main/mcp_manager.py): integration · Loads and coordinates configured MCP servers. · `mcp_manager.py`
- [MCP client](https://github.com/abheytiwari/codi/blob/main/mcp_client.py): protocol client · Connects to MCP servers and exchanges tool messages. · `mcp_client.py`

### Context

State, memory, trimming, and codebase retrieval.

- [Run state](https://github.com/abheytiwari/codi/blob/main/state/temp_db.py): session state · Per-run iteration data and step outputs. · `state/temp_db.py`
- [Memory](https://github.com/abheytiwari/codi/blob/main/memory.py): history store · Conversation history and compression across turns. · `memory.py`
- [Context trimmer](https://github.com/abheytiwari/codi/blob/main/context_trimmer.py): budget guard · Trims or summarizes context to fit token limits. · `context_trimmer.py`
- [Indexer](https://github.com/abheytiwari/codi/blob/main/indexer.py): retrieval · Builds and queries the local codebase index. · `indexer.py`

### Provider and observability

LLM abstraction, config, logging, and diagnostics.

- [LLM factory](https://github.com/abheytiwari/codi/blob/main/llm_factory.py): provider abstraction · Unifies local and cloud model backends behind one interface. · `llm_factory.py`
- [Config](https://github.com/abheytiwari/codi/blob/main/config.py): runtime config · Selects providers, models, and runtime behavior. · `config.py`
- [Logger](https://github.com/abheytiwari/codi/blob/main/logger.py): structured logging · Writes structured events to codi.log. · `logger.py`
- [Log viewer](https://github.com/abheytiwari/codi/blob/main/log_viewer.py): telemetry UI · Live view of tool calls, decisions, and failures. · `log_viewer.py`

## Connections

- 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.
