# rasbt/mini-coding-agent architecture

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

- Interactive diagram: https://gitdiagram.com/rasbt/mini-coding-agent
- Repository: https://github.com/rasbt/mini-coding-agent

## Overview

1. **Overall shape**
   - This repo is a single-file Python application centered on `mini_coding_agent.py`, with a thin packaging layer in `pyproject.toml`, a CLI entry point (`mini-coding-agent`), and a small test suite under `tests/`.
   - Architecturally it is a local, interactive agent harness rather than a multi-service system.

2. **Core runtime**
   - The main executable is the agent loop in `mini_coding_agent.py`.
   - It is responsible for reading CLI flags, loading or creating session state, collecting workspace context, calling the model backend, parsing tool/final outputs, and advancing the turn loop until completion or limits are reached.

3. **Model/backend boundary**
   - The agent talks to a local Ollama server over HTTP, specifically Ollama’s `/api/generate` endpoint.
   - Ollama is an external runtime dependency, but the repo itself has no nonstandard Python dependencies beyond the standard library, which keeps the architecture lightweight and self-contained.

4. **Workspace boundary**
   - The agent operates against a chosen workspace root via `--cwd` and treats that directory as the editable boundary.
   - It snapshots workspace facts up front, such as repo layout, instructions, and git state, to build a stable context for the model.

5. **Prompt and turn-state management**
   - The repo emphasizes a stable prompt prefix separated from changing user/task state, transcript, and memory.
   - This matters architecturally because repeated model calls can reuse static context while the agent only appends the delta for each turn, reducing prompt churn.

6. **Tooling subsystem**
   - The model is not allowed to act freely; it must request named tools through structured outputs.
   - Tool inputs are validated, workspace paths are checked, and risky operations such as shell commands and file writes are gated by an approval policy (`ask`, `auto`, or `never`).

7. **Approval and safety boundary**
   - There is a clear trust boundary between “read/inspect” actions and “write/execute” actions.
   - In `ask` mode the user becomes part of the control flow before risky operations occur; in `auto` the model can execute them directly; in `never` those actions are blocked.

8. **State persistence and resumption**
   - Sessions are persisted under `.mini-coding-agent/sessions/` inside the target workspace.
   - The persistent state includes a durable transcript plus distilled working memory, enabling `--resume latest` or a specific session ID to restore the agent’s prior context.

9. **Context reduction**
   - The agent actively manages context size by clipping long outputs, deduplicating repeated reads, and compressing older transcript entries.
   - This is a key internal subsystem because it prevents the conversation state from growing without bound during extended coding sessions.

10. **Delegation model**
   - The repo supports bounded delegation to helper/subagents for scoped subtasks.
   - These delegates inherit enough context to be useful but are intentionally limited, so they remain subordinate to the main session and its workspace boundaries.

11. **Interactive command channel**
   - REPL slash commands such as `/help`, `/memory`, `/session`, `/reset`, and `/exit` are handled by the agent itself rather than being sent to the model.
   - This creates a separate control path for user/session management alongside the normal natural-language task loop.

12. **Testing and CI**
   - The repository includes `tests/test_mini_coding_agent.py` and a GitHub Actions workflow in `.github/workflows/ci.yml`.
   - This suggests the project is validated as a small, self-contained CLI/tooling package, with CI likely focused on Python correctness and regression checks rather than deployment.

13. **How to diagram it**
   - A good architecture diagram would show: user/CLI → agent loop → workspace/session state → Ollama model backend, with side paths for tool execution, approval gating, persistence to session files, and optional bounded delegation.
   - The most important boundaries are the local workspace, the external Ollama process, and the approval gate around any action that can modify the filesystem or execute commands.

Main entry points: [`mini_coding_agent.py`](https://github.com/rasbt/mini-coding-agent/blob/main/mini_coding_agent.py) (Agent loop), [`tests/test_mini_coding_agent.py`](https://github.com/rasbt/mini-coding-agent/blob/main/tests/test_mini_coding_agent.py) (Tests), [`pyproject.toml`](https://github.com/rasbt/mini-coding-agent/blob/main/pyproject.toml) (CLI entry), [`.github/workflows/ci.yml`](https://github.com/rasbt/mini-coding-agent/blob/main/.github/workflows/ci.yml) (CI workflow)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Core runtime"]
  node_cli_entry["CLI entry<br/>command entry<br/>[pyproject.toml]"]
  node_agent_loop(("Agent loop<br/>runtime loop"))
  node_arg_config["Args config<br/>cli parsing"]
  node_prompt_state["Prompt state<br/>context builder"]
  node_workspace_snapshot["Workspace snapshot<br/>repo context"]
  node_session_store[("Session store<br/>persistent state")]
  node_context_reducer["Context reducer<br/>memory management"]
  node_tool_router["Tool router<br/>tooling"]
  node_approval_gate{{"Approval gate<br/>safety policy"}}
  node_delegation["Delegation<br/>subagent support"]
  node_slash_commands["Slash commands<br/>interactive control"]
end

subgraph group_boundary["Boundaries"]
  node_model_client(("Model client<br/>ollama client"))
  node_ollama_api{{"Ollama API<br/>external runtime"}}
  node_workspace_tools["Workspace tools<br/>file and shell actions"]
end

subgraph group_ops["Verification"]
  node_tests["Tests<br/>pytest"]
  node_ci["CI workflow<br/>github actions<br/>[ci.yml]"]
end

node_cli_entry -->|"starts"| node_arg_config
node_arg_config -->|"configures"| node_agent_loop
node_agent_loop -->|"builds"| node_prompt_state
node_agent_loop -->|"reads"| node_workspace_snapshot
node_agent_loop -->|"resumes"| node_session_store
node_agent_loop -->|"manages"| node_context_reducer
node_agent_loop -->|"calls"| node_model_client
node_model_client -->|"http"| node_ollama_api
node_model_client -->|"returns"| node_tool_router
node_tool_router -->|"checks"| node_approval_gate
node_approval_gate -->|"permits"| node_workspace_tools
node_approval_gate -->|"records"| node_session_store
node_workspace_tools -->|"updates"| node_agent_loop
node_agent_loop -->|"spawns"| node_delegation
node_slash_commands -->|"controls"| node_agent_loop
node_tests -->|"covers"| node_agent_loop
node_ci -->|"runs"| node_tests

click node_cli_entry "https://github.com/rasbt/mini-coding-agent/blob/main/pyproject.toml"
click node_agent_loop "https://github.com/rasbt/mini-coding-agent/blob/main/mini_coding_agent.py"
click node_arg_config "https://github.com/rasbt/mini-coding-agent/blob/main/mini_coding_agent.py"
click node_prompt_state "https://github.com/rasbt/mini-coding-agent/blob/main/mini_coding_agent.py"
click node_workspace_snapshot "https://github.com/rasbt/mini-coding-agent/blob/main/mini_coding_agent.py"
click node_session_store "https://github.com/rasbt/mini-coding-agent/blob/main/mini_coding_agent.py"
click node_context_reducer "https://github.com/rasbt/mini-coding-agent/blob/main/mini_coding_agent.py"
click node_model_client "https://github.com/rasbt/mini-coding-agent/blob/main/mini_coding_agent.py"
click node_tool_router "https://github.com/rasbt/mini-coding-agent/blob/main/mini_coding_agent.py"
click node_approval_gate "https://github.com/rasbt/mini-coding-agent/blob/main/mini_coding_agent.py"
click node_delegation "https://github.com/rasbt/mini-coding-agent/blob/main/mini_coding_agent.py"
click node_slash_commands "https://github.com/rasbt/mini-coding-agent/blob/main/mini_coding_agent.py"
click node_tests "https://github.com/rasbt/mini-coding-agent/blob/main/tests/test_mini_coding_agent.py"
click node_ci "https://github.com/rasbt/mini-coding-agent/blob/main/.github/workflows/ci.yml"

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_entry,node_agent_loop,node_arg_config,node_prompt_state,node_workspace_snapshot,node_session_store,node_context_reducer,node_tool_router,node_approval_gate,node_delegation,node_slash_commands toneBlue
class node_model_client,node_ollama_api,node_workspace_tools toneAmber
class node_tests,node_ci toneMint
```

## Components

### Core runtime

Main agent loop and its internal subsystems

- [CLI entry](https://github.com/rasbt/mini-coding-agent/blob/main/pyproject.toml): command entry · Invokes the agent from the installed script · `pyproject.toml`
- [Agent loop](https://github.com/rasbt/mini-coding-agent/blob/main/mini_coding_agent.py): runtime loop · Coordinates turns until completion or limits are reached · `mini_coding_agent.py`
- [Args config](https://github.com/rasbt/mini-coding-agent/blob/main/mini_coding_agent.py): cli parsing · Reads flags such as workspace, resume, and approval mode · `mini_coding_agent.py`
- [Prompt state](https://github.com/rasbt/mini-coding-agent/blob/main/mini_coding_agent.py): context builder · Separates stable instructions from changing task state · `mini_coding_agent.py`
- [Workspace snapshot](https://github.com/rasbt/mini-coding-agent/blob/main/mini_coding_agent.py): repo context · Collects layout, instructions, and git state from the target workspace · `mini_coding_agent.py`
- [Session store](https://github.com/rasbt/mini-coding-agent/blob/main/mini_coding_agent.py): persistent state · Loads and saves transcripts and working memory for resumption · `mini_coding_agent.py`
- [Context reducer](https://github.com/rasbt/mini-coding-agent/blob/main/mini_coding_agent.py): memory management · Clips, deduplicates, and compresses growing conversation state · `mini_coding_agent.py`
- [Tool router](https://github.com/rasbt/mini-coding-agent/blob/main/mini_coding_agent.py): tooling · Interprets structured tool requests from the model · `mini_coding_agent.py`
- [Approval gate](https://github.com/rasbt/mini-coding-agent/blob/main/mini_coding_agent.py): safety policy · Controls risky write and execute actions via ask, auto, or never · `mini_coding_agent.py`
- [Delegation](https://github.com/rasbt/mini-coding-agent/blob/main/mini_coding_agent.py): subagent support · Runs bounded helper tasks with restricted context · `mini_coding_agent.py`
- [Slash commands](https://github.com/rasbt/mini-coding-agent/blob/main/mini_coding_agent.py): interactive control · Handles /help, /memory, /session, /reset, and /exit locally · `mini_coding_agent.py`

### Boundaries

External runtime and workspace boundaries

- [Model client](https://github.com/rasbt/mini-coding-agent/blob/main/mini_coding_agent.py): ollama client · Calls the local Ollama generate endpoint over HTTP · `mini_coding_agent.py`
- **Ollama API**: external runtime · Local model backend outside the repository
- **Workspace tools**: file and shell actions · Performs validated reads, writes, and commands inside the workspace boundary

### Verification

Tests and CI

- [Tests](https://github.com/rasbt/mini-coding-agent/blob/main/tests/test_mini_coding_agent.py): pytest · Regression coverage for the agent behavior · `tests/test_mini_coding_agent.py`
- [CI workflow](https://github.com/rasbt/mini-coding-agent/blob/main/.github/workflows/ci.yml): github actions · Automated validation in GitHub Actions · `.github/workflows/ci.yml`

## Connections

- CLI entry → Args config: starts · Loads runtime configuration from CLI input
- Args config → Agent loop: configures · Passes parsed flags into the main loop
- Agent loop → Prompt state: builds · Constructs the reusable prompt prefix and turn state
- Agent loop → Workspace snapshot: reads · Captures workspace facts before model calls
- Agent loop → Session store: resumes · Restores or initializes durable session state
- Agent loop → Context reducer: manages · Keeps the conversation within context limits
- Agent loop → Model client: calls · Sends prompts and receives model responses
- Model client → Ollama API: http · Uses the local Ollama generate endpoint
- Model client → Tool router: returns · Feeds structured outputs back into the agent
- Tool router → Approval gate: checks · Determines whether an action needs permission
- Approval gate → Workspace tools: permits · Allows safe execution when policy and user consent allow it
- Approval gate → Session store: records · Persists decisions and updated state
- Workspace tools → Agent loop: updates · Returns tool results into the next turn
- Agent loop → Delegation: spawns · Creates bounded helper tasks when useful
- Slash commands → Agent loop: controls · Intercepts local REPL commands outside the model path
- Tests → Agent loop: covers · Exercises the main application behavior
- CI workflow → Tests: runs · Validates the project in automation
