How rasbt/mini-coding-agent works
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 Agent loop · test_mini_coding_agent.py Tests · pyproject.toml CLI entry · ci.yml CI workflow
Components 16
Core runtime
Main agent loop and its internal subsystems
- CLI entry · Invokes the agent from the installed script
pyproject.toml - Agent loop · Coordinates turns until completion or limits are reached
mini_coding_agent.py - Args config · Reads flags such as workspace, resume, and approval mode
mini_coding_agent.py - Prompt state · Separates stable instructions from changing task state
mini_coding_agent.py - Workspace snapshot · Collects layout, instructions, and git state from the target workspace
mini_coding_agent.py - Session store · Loads and saves transcripts and working memory for resumption
mini_coding_agent.py - Context reducer · Clips, deduplicates, and compresses growing conversation state
mini_coding_agent.py - Tool router · Interprets structured tool requests from the model
mini_coding_agent.py - Approval gate · Controls risky write and execute actions via ask, auto, or never
mini_coding_agent.py - Delegation · Runs bounded helper tasks with restricted context
mini_coding_agent.py - Slash commands · Handles /help, /memory, /session, /reset, and /exit locally
mini_coding_agent.py
Boundaries
External runtime and workspace boundaries
- Model client · Calls the local Ollama generate endpoint over HTTP
mini_coding_agent.py - Ollama API · Local model backend outside the repository
- Workspace tools · Performs validated reads, writes, and commands inside the workspace boundary
Verification
Tests and CI
- Tests · Regression coverage for the agent behavior
tests/test_mini_coding_agent.py - CI workflow · Automated validation in GitHub Actions
.github/workflows/ci.yml
Connections 17
- 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