# colin781/mini-pi architecture

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

- Interactive diagram: https://gitdiagram.com/colin781/mini-pi
- Repository: https://github.com/colin781/mini-pi

## Overview

Mini Pi is a terminal coding agent: a user submits a repository task, the agent consults a model and workspace tools, applies guarded edits, runs verification, and presents a report. The REPL adds chat/task routing, persistent sessions, context reuse, and change review; configuration selects providers and runtime behavior. Separate evaluation tooling runs reproducible tasks and checks results. The graph preserves README-documented capabilities whose implementation was not sampled, but omits uncertain internal links where excerpts do not establish a call.

Main entry points: [`agent.py`](https://github.com/colin781/mini-pi/blob/main/agent.py) (Coding agent loop), [`mini_pi/tools.py`](https://github.com/colin781/mini-pi/blob/main/mini_pi/tools.py) (Tool executor), [`mini_pi/repl.py`](https://github.com/colin781/mini-pi/blob/main/mini_pi/repl.py) (Interactive REPL), [`mini_pi/cli.py`](https://github.com/colin781/mini-pi/blob/main/mini_pi/cli.py) (CLI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry and interaction"]
  node_cli["CLI<br/>[cli.py]"]
  node_repl["Interactive REPL<br/>[repl.py]"]
  node_config["Configuration<br/>[config.py]"]
end

subgraph group_agent["Agent runtime"]
  node_agentcore["Coding agent loop<br/>[agent.py]"]
  node_model["Model backend<br/>[model_backend.py]"]
  node_chat["Lightweight chat<br/>[chat.py]"]
  node_context["Context budgeting<br/>[context.py]"]
end

subgraph group_workspace["Workspace operations"]
  node_tools["Tool executor<br/>[tools.py]"]
  node_repository["Repository index<br/>[repository.py]"]
  node_patching["Patch application<br/>[patching.py]"]
  node_policy["Command policy<br/>[command_policy.py]"]
  node_protection["Path protection<br/>[protection.py]"]
  node_checkpoints["File checkpoints<br/>[checkpoints.py]"]
  node_verification["Task verification<br/>[verification.py]"]
end

subgraph group_state["State and results"]
  node_sessions[("Session persistence<br/>[sessions.py]")]
  node_conversation["Conversation handling<br/>[conversation.py]"]
  node_changes["Change tracking<br/>[change_tracking.py]"]
  node_report["Run reports<br/>[reporting.py]"]
  node_trace["Run tracing<br/>[tracing.py]"]
  node_terminal["Terminal presentation<br/>[terminal_ui.py]"]
end

subgraph group_evaluation["Evaluation"]
  node_evaluation["Evaluation runner<br/>[evaluation.py]"]
  node_evalcli["Evaluation CLI<br/>[eval_cli.py]"]
end

node_user(("User"))
node_modelservice{{"Ollama / DeepSeek"}}

node_user -->|"starts task"| node_cli
node_cli -->|"loads settings"| node_config
node_cli -->|"starts REPL"| node_repl
node_cli -->|"runs task"| node_agentcore
node_repl -->|"dispatches tasks"| node_agentcore
node_repl -->|"routes chat"| node_chat
node_repl -->|"persists sessions"| node_sessions
node_repl -->|"reuses context"| node_conversation
node_repl -->|"selects provider"| node_model
node_agentcore -->|"requests completions"| node_model
node_model -->|"sends requests"| node_modelservice
node_agentcore -->|"budgets context"| node_context
node_agentcore -->|"executes tool calls"| node_tools
node_tools -->|"indexes workspace"| node_repository
node_tools -->|"applies patches"| node_patching
node_tools -->|"checks commands"| node_policy
node_tools -->|"checks paths"| node_protection
node_tools -->|"creates checkpoints"| node_checkpoints
node_tools -->|"tracks edits"| node_changes
node_agentcore -->|"runs acceptance"| node_verification
node_agentcore -->|"restores attempts"| node_checkpoints
node_agentcore -->|"builds report"| node_report
node_agentcore -->|"records events"| node_trace
node_agentcore -->|"presents result"| node_terminal
node_evalcli -->|"runs evaluations"| node_evaluation
node_evaluation -->|"launches agent"| node_agentcore
node_evaluation -->|"checks outcomes"| node_verification
node_evaluation -->|"reads run reports"| node_report

click node_cli "https://github.com/colin781/mini-pi/blob/main/mini_pi/cli.py"
click node_repl "https://github.com/colin781/mini-pi/blob/main/mini_pi/repl.py"
click node_config "https://github.com/colin781/mini-pi/blob/main/mini_pi/config.py"
click node_agentcore "https://github.com/colin781/mini-pi/blob/main/agent.py"
click node_model "https://github.com/colin781/mini-pi/blob/main/mini_pi/model_backend.py"
click node_chat "https://github.com/colin781/mini-pi/blob/main/mini_pi/chat.py"
click node_context "https://github.com/colin781/mini-pi/blob/main/mini_pi/context.py"
click node_tools "https://github.com/colin781/mini-pi/blob/main/mini_pi/tools.py"
click node_repository "https://github.com/colin781/mini-pi/blob/main/mini_pi/repository.py"
click node_patching "https://github.com/colin781/mini-pi/blob/main/mini_pi/patching.py"
click node_policy "https://github.com/colin781/mini-pi/blob/main/mini_pi/command_policy.py"
click node_protection "https://github.com/colin781/mini-pi/blob/main/mini_pi/protection.py"
click node_checkpoints "https://github.com/colin781/mini-pi/blob/main/mini_pi/checkpoints.py"
click node_verification "https://github.com/colin781/mini-pi/blob/main/mini_pi/verification.py"
click node_sessions "https://github.com/colin781/mini-pi/blob/main/mini_pi/sessions.py"
click node_conversation "https://github.com/colin781/mini-pi/blob/main/mini_pi/conversation.py"
click node_changes "https://github.com/colin781/mini-pi/blob/main/mini_pi/change_tracking.py"
click node_report "https://github.com/colin781/mini-pi/blob/main/mini_pi/reporting.py"
click node_trace "https://github.com/colin781/mini-pi/blob/main/mini_pi/tracing.py"
click node_terminal "https://github.com/colin781/mini-pi/blob/main/mini_pi/terminal_ui.py"
click node_evaluation "https://github.com/colin781/mini-pi/blob/main/mini_pi/evaluation.py"
click node_evalcli "https://github.com/colin781/mini-pi/blob/main/mini_pi/eval_cli.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_repl,node_config,node_user toneBlue
class node_agentcore,node_model,node_chat,node_context toneAmber
class node_tools,node_repository,node_patching,node_policy,node_protection,node_checkpoints,node_verification toneMint
class node_sessions,node_conversation,node_changes,node_report,node_trace,node_terminal toneRose
class node_evaluation,node_evalcli,node_modelservice toneIndigo
```

## Components

### Entry and interaction

- [CLI](https://github.com/colin781/mini-pi/blob/main/mini_pi/cli.py): `mini_pi/cli.py`
- [Interactive REPL](https://github.com/colin781/mini-pi/blob/main/mini_pi/repl.py): `mini_pi/repl.py`
- [Configuration](https://github.com/colin781/mini-pi/blob/main/mini_pi/config.py): `mini_pi/config.py`

### Agent runtime

- [Coding agent loop](https://github.com/colin781/mini-pi/blob/main/agent.py): `agent.py`
- [Model backend](https://github.com/colin781/mini-pi/blob/main/mini_pi/model_backend.py): `mini_pi/model_backend.py`
- [Lightweight chat](https://github.com/colin781/mini-pi/blob/main/mini_pi/chat.py): `mini_pi/chat.py`
- [Context budgeting](https://github.com/colin781/mini-pi/blob/main/mini_pi/context.py): `mini_pi/context.py`

### Workspace operations

- [Tool executor](https://github.com/colin781/mini-pi/blob/main/mini_pi/tools.py): `mini_pi/tools.py`
- [Repository index](https://github.com/colin781/mini-pi/blob/main/mini_pi/repository.py): `mini_pi/repository.py`
- [Patch application](https://github.com/colin781/mini-pi/blob/main/mini_pi/patching.py): `mini_pi/patching.py`
- [Command policy](https://github.com/colin781/mini-pi/blob/main/mini_pi/command_policy.py): `mini_pi/command_policy.py`
- [Path protection](https://github.com/colin781/mini-pi/blob/main/mini_pi/protection.py): `mini_pi/protection.py`
- [File checkpoints](https://github.com/colin781/mini-pi/blob/main/mini_pi/checkpoints.py): `mini_pi/checkpoints.py`
- [Task verification](https://github.com/colin781/mini-pi/blob/main/mini_pi/verification.py): `mini_pi/verification.py`

### State and results

- [Session persistence](https://github.com/colin781/mini-pi/blob/main/mini_pi/sessions.py): `mini_pi/sessions.py`
- [Conversation handling](https://github.com/colin781/mini-pi/blob/main/mini_pi/conversation.py): `mini_pi/conversation.py`
- [Change tracking](https://github.com/colin781/mini-pi/blob/main/mini_pi/change_tracking.py): `mini_pi/change_tracking.py`
- [Run reports](https://github.com/colin781/mini-pi/blob/main/mini_pi/reporting.py): `mini_pi/reporting.py`
- [Run tracing](https://github.com/colin781/mini-pi/blob/main/mini_pi/tracing.py): `mini_pi/tracing.py`
- [Terminal presentation](https://github.com/colin781/mini-pi/blob/main/mini_pi/terminal_ui.py): `mini_pi/terminal_ui.py`

### Evaluation

- [Evaluation runner](https://github.com/colin781/mini-pi/blob/main/mini_pi/evaluation.py): `mini_pi/evaluation.py`
- [Evaluation CLI](https://github.com/colin781/mini-pi/blob/main/mini_pi/eval_cli.py): `mini_pi/eval_cli.py`

### Other components

- **User**
- **Ollama / DeepSeek**

## Connections

- User → CLI: starts task
- CLI → Configuration: loads settings (evidence: `mini_pi/cli.py`)
- CLI → Interactive REPL: starts REPL (evidence: `mini_pi/cli.py`)
- CLI → Coding agent loop: runs task (evidence: `mini_pi/cli.py`)
- Interactive REPL → Coding agent loop: dispatches tasks (evidence: `mini_pi/repl.py`)
- Interactive REPL → Lightweight chat: routes chat (evidence: `mini_pi/repl.py`)
- Interactive REPL → Session persistence: persists sessions (evidence: `mini_pi/repl.py`)
- Interactive REPL → Conversation handling: reuses context (evidence: `mini_pi/repl.py`)
- Interactive REPL → Model backend: selects provider (evidence: `mini_pi/repl.py`)
- Coding agent loop → Model backend: requests completions (evidence: `agent.py`)
- Model backend → Ollama / DeepSeek: sends requests
- Coding agent loop → Context budgeting: budgets context (evidence: `agent.py`)
- Coding agent loop → Tool executor: executes tool calls (evidence: `agent.py`)
- Tool executor → Repository index: indexes workspace (evidence: `mini_pi/tools.py`)
- Tool executor → Patch application: applies patches (evidence: `mini_pi/tools.py`)
- Tool executor → Command policy: checks commands (evidence: `mini_pi/tools.py`)
- Tool executor → Path protection: checks paths (evidence: `mini_pi/tools.py`)
- Tool executor → File checkpoints: creates checkpoints (evidence: `mini_pi/tools.py`)
- Tool executor → Change tracking: tracks edits (evidence: `mini_pi/tools.py`)
- Coding agent loop → Task verification: runs acceptance (evidence: `agent.py`)
- Coding agent loop → File checkpoints: restores attempts (evidence: `agent.py`)
- Coding agent loop → Run reports: builds report (evidence: `agent.py`)
- Coding agent loop → Run tracing: records events (evidence: `agent.py`)
- Coding agent loop → Terminal presentation: presents result (evidence: `agent.py`)
- Evaluation CLI → Evaluation runner: runs evaluations (evidence: `mini_pi/eval_cli.py`)
- Evaluation runner → Coding agent loop: launches agent (evidence: `mini_pi/evaluation.py`)
- Evaluation runner → Task verification: checks outcomes (evidence: `mini_pi/evaluation.py`)
- Evaluation runner → Run reports: reads run reports (evidence: `mini_pi/evaluation.py`)
