rasbt/mini-coding-agent: a readable Ollama harness for studying coding agent architecture
Minimal and readable coding agent harness implementation in Python to explain the core components of coding agents.
At a glance
- What is it?
- A single-file Python coding agent built to explain the components of a coding agent rather than to ship one. It runs against a local Ollama model, gates risky tools behind approval, and keeps sessions on disk. The README calls it optimized for readability, not robustness, and that framing should decide whether you adopt it.
- Who is it for?
- Use rasbt/mini-coding-agent if you want to read one Python file and understand how a coding agent collects repo context, shapes prompts, validates tool calls, handles approvals, persists transcripts, and bounds delegation. Do not adopt it as production tooling.
- Can I use it commercially?
- Yes. Apache-2.0 is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 161 days ago.
- What is it written in?
- Mainly Python, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The problem it addresses: a coding agent you can read in one sitting
Most coding agents arrive as products. You get a binary, a plugin, a hosted service, and a changelog. If you want to know how the loop actually works, you are reading minified JavaScript or reverse-engineering an API. rasbt/mini-coding-agent takes the opposite position. The README describes it as a "minimal local agent loop" and the repository confirms the scale: a single module, `mini_coding_agent.py`, plus `EXAMPLE.md`, a `pyproject.toml`, a `tests/` directory, and a `LICENSE`.
The intended reader is an engineer who wants to build or evaluate a coding agent and needs a reference implementation small enough to hold in their head. The README frames the project around six building blocks: live repo context, prompt shape and cache reuse, structured tools with validation and permissions, context reduction and output management, transcripts and resumption, and bounded delegation. Those six headings are the actual curriculum. The code is the illustration.
This is not a tool for a team that wants an agent to refactor a monorepo. It is a tool for the person who has to decide how that agent should be built. The distinction matters because almost every design choice in the repository trades capability for legibility, and the README says so: the agent is "intentionally small and optimized for readability, not robustness."
How the loop works: stable prompt, structured tools, bounded turns
The mechanism is a turn loop with a hard step budget. `--max-steps` defaults to 6, which caps how many model and tool turns a single user request may consume. Each turn sends a prompt to Ollama's `/api/generate` endpoint and reads back text that must contain either `<tool>...</tool>` or `<final>...</final>`. That tag convention is the entire protocol. The README warns that "different Ollama models will follow those instructions with different reliability" and suggests switching to a stronger instruction-following model when the format breaks down.
Around that protocol sit four mechanisms worth understanding. First, workspace snapshot collection: the agent gathers stable facts such as repo layout, instructions, and git state before the conversation starts. Second, prompt shape: the static prefix is kept separate from the changing request, transcript, and memory so repeated model calls can reuse the static parts. Third, tool validation: the model acts through named tools with checked inputs and workspace path validation, and risky tools pass through an approval gate. Fourth, context reduction: long outputs are clipped, repeated reads are deduplicated, and older transcript entries are compressed.
Two stores persist across turns. A full durable transcript is written to disk, while a smaller working memory holds the distilled state: current task, tracked files, and notes. Resumption reads from those. Delegation is the sixth piece, described in the README as scoped subtasks handed to helper agents that inherit enough context to be useful but operate within limits. The README does not document how those limits are computed, which is one of the places where the tutorial article is doing work the repository does not.
Installing it and running a first session against a local model
The prerequisites are Python 3.10 or newer, Ollama installed, and an Ollama model pulled locally. The README notes the project has no Python runtime dependency beyond the standard library, so `python mini_coding_agent.py` works without any environment manager. `uv` is optional and provides the `mini-coding-agent` CLI entry point declared in `pyproject.toml`.
Install Ollama first so the `ollama` command exists in your shell, then confirm it responds:
ollama --helpStart the server in one terminal and leave it running:
ollama serveIn another terminal, pull the model the project defaults to:
ollama pull qwen3.5:4bThe README suggests trying a larger variant such as `qwen3.5:9b` if you have sufficient memory. Now clone and enter the repository:
git clone https://github.com/rasbt/mini-coding-agent.git
cd mini-coding-agentStart the agent with the default model and the default `ask` approval mode:
uv run mini-coding-agentWithout `uv`, the equivalent is `python mini_coding_agent.py` from the same directory. You should land in a REPL where slash commands are handled by the agent itself rather than sent to the model. `/help` lists them, `/memory` prints the distilled session memory including current task, tracked files, and notes, and `/session` prints the path to the saved session JSON file. `/exit` and `/quit` leave. For a worked example, the README points at `EXAMPLE.md` in the repository root.
To point the agent at a different directory, pass `--cwd`; to use a different model, pass `--model`. The full flag list is available through `uv run mini-coding-agent --help`.
Approval modes and the auto mode you should think twice about
Risky tools, meaning shell commands and file writes, are gated. Three modes exist. `--approval ask` prompts before risky actions and is both the default and the mode the README recommends. `--approval never` denies them outright. `--approval auto` allows them automatically, and the README is unusually direct about the consequence: it permits "arbitrary command execution and file writes by the model" and should be used only with trusted prompts and trusted repositories.
That warning is the honest part of the design. A coding agent that can write files and run shell commands has the same reach as the person running it. The approval gate is the only thing standing between a malformed model output and your working tree. The README does not document a sandbox, a container boundary, or a filesystem allowlist beyond workspace path validation on tool inputs. If you are evaluating this project as a base for something real, the approval layer is the component to read first and the one most likely to need replacement.
Session persistence deserves the same scrutiny. Sessions are saved under the target workspace root in `.mini-coding-agent/sessions/`. That directory will contain your transcript, which means whatever you typed, whatever the agent read, and whatever the model produced. Resuming is a flag away: `--resume latest` picks up the most recent session, and `--resume 20260401-144025-2dd0aa` targets a specific id. The README does not document rollback of file changes the agent made, so a resumed session restores conversational state, not your repository.
Where it is the wrong tool
The README's own sentence is the limitation: intentionally small, optimized for readability, not robustness. Concretely, that means the agent depends on the model emitting well-formed `<tool>` or `<final>` tags. When a model drifts, the loop has nothing to fall back on except the suggestion to try a stronger instruction-following model. There is no schema validation layer described beyond checked tool inputs.
Step budget is another boundary. `--max-steps` defaults to 6 and `--max-new-tokens` defaults to 512 per step. A task that needs twenty tool calls will not finish inside the default budget. You can raise the flags, but the defaults tell you what kind of task the author had in mind: short, inspectable interactions, not long autonomous runs.
The backend is Ollama, and the README says "currently," which is a quiet admission that other providers are not supported today. If your environment standardizes on a hosted API, this harness does not meet you there. There is also no release history in the repository metadata, so there is no versioned artifact to pin and no changelog to read before upgrading. You are tracking `main`.
Finally, there is no documented rollback, no documented sandbox, and no documented multi-user story. A shared machine running this with `--approval auto` against a repository containing secrets is the failure mode the README is warning you about.
How it differs from Aider and other full coding agents
Aider is the natural comparison because it occupies the same slot: a terminal coding agent that edits files in your repository. The difference is scope and intent. Aider is a maintained application with its own edit-format machinery, repository map construction, git integration, and provider support spanning many backends. rasbt/mini-coding-agent is a teaching artifact with one module, one backend, and a README that points at a magazine article for the full explanation.
A second comparison is a general-purpose agent framework such as LangChain or the OpenAI Agents SDK. Those give you orchestration primitives and let you assemble a coding agent yourself. mini-coding-agent gives you the assembled loop and asks you to read it. The trade is reversed: frameworks give you breadth and hide the loop; this gives you the loop and hides nothing.
A third reference point is the hosted coding agent inside an IDE. Those optimize for latency, index quality, and edit accuracy across large repositories. mini-coding-agent optimizes for the reader. If your goal is to understand why a coding agent clips long outputs, deduplicates repeated reads, and separates a stable prompt prefix from a changing transcript, this repository shows those decisions in Python. If your goal is to ship, the other three categories will get you there sooner.
Licence, maintenance and what an upgrade costs you
The project is Apache-2.0, which permits commercial use, modification, and redistribution provided you preserve the licence and notices and state significant changes. That is a permissive licence, not a copyleft one, so incorporating the loop into a larger system does not obligate you to publish that system. This is a description of the licence text, not legal advice; if the distinction matters to your organisation, have counsel read the file in the repository root.
The maintenance picture is thin in a specific way. The repository is not archived, and the last push was on 2026-04-07. There are no retrieved releases, so there is no version to upgrade to or from. `pyproject.toml` declares version `0.1.0` and a single runtime dependency, `pytest>=9.0.2`, which is unusual for a runtime dependency list and suggests the packaging metadata was not tuned for distribution. The declared script entry point is `mini-coding-agent = "mini_coding_agent:main"`.
Upgrade cost is therefore measured in re-reading, not in migration guides. Because there is one module and no release cadence, the practical approach is to vendor the file or fork it and diff against upstream when you care. The absence of a changelog means you cannot know what changed between two points without reading the commits.
Editorial conclusion
Use rasbt/mini-coding-agent if you want to read one Python file and understand how a coding agent collects repo context, shapes prompts, validates tool calls, handles approvals, persists transcripts, and bounds delegation. Do not adopt it as production tooling. The README states the agent is intentionally small and optimized for readability rather than robustness, the model backend is currently Ollama only, and the project has no release history to upgrade against. Before running it anywhere that matters, verify three things: that your Ollama model reliably emits the `<tool>` and `<final>` tags the loop expects, that `--approval ask` is the mode in effect, and that `.mini-coding-agent/sessions/` under your workspace root is somewhere you are willing to have transcripts written.
Frequently asked questions
What model does rasbt/mini-coding-agent use by default?
The README states the default is `qwen3.5:4b`, pulled through Ollama, and that the agent sends prompts to Ollama's `/api/generate` endpoint. It suggests trying a larger variant such as `qwen3.5:9b` if you have sufficient memory. The backend is described as currently Ollama-based.
Do I need uv to run rasbt/mini-coding-agent?
No. The README says the project has no Python runtime dependency beyond the standard library, so you can run `python mini_coding_agent.py` directly. `uv` is listed as optional and provides the `mini-coding-agent` CLI entry point.
Where does rasbt/mini-coding-agent save sessions?
The README says sessions are saved under the target workspace root in `.mini-coding-agent/sessions/`. You can resume the latest one with `--resume latest` or target a specific id such as `20260401-144025-2dd0aa`.
Is it safe to run rasbt/mini-coding-agent with --approval auto?
The README warns that `auto` allows risky actions automatically, including arbitrary command execution and file writes by the model, and says to use it only with trusted prompts and trusted repositories. The default and recommended mode is `ask`.
Community notes