mini-coding-agent ships pytest as a runtime dependency and says it has none
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 agent harness built to be read rather than trusted, whose packaging contradicts its own no-dependency claim, whose tool protocol is angle-bracket tags in generated prose, and whose default engine is the smallest model the file recommends against.
- Who is it for?
- mini-coding-agent is worth reading rather than adopting, and those are different activities. As a teaching artefact it is close to ideal: six components, one file, no framework, a prompt you can print, and a flag list that tells you every knob including the ones most harnesses hide.
- 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?
- Activity is slowing. The repository last received commits 7 months 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 November 15, 2026, and from our analysis. They are not legal advice.
Star history
- rasbt/mini-coding-agent1,233 ★ · +58
| Repository | 2026-09-22 | 2026-11-15 |
|---|---|---|
| rasbt/mini-coding-agent | 1.2k | 1.2k |
58 Stars in the last 54 days, measured from the daily GitHub snapshot. Compare with other projects
Editorial analysis
The stated goal is to be read, and the file says so in its last line
The repository description ends with a purpose clause: this is an implementation in Python to explain the core components of coding agents. Not to ship an agent. To explain one.
The last note in the readme makes the trade explicit. The agent is intentionally small and optimised for readability rather than for anything else.
The code matches the claim. The root of the repository has eight entries, and the agent is one of them: a single Python module. There is a tests directory, an example file, a licence, a readme and the packaging metadata. Six components are described in the readme, and all six live in that one file, which the packaging configuration confirms by declaring a list of top-level modules rather than packages.
So when a component is missing, the answer is not that it lives in another file. There is no other file. That is the appeal of the project for somebody learning how these harnesses work, and it is also why none of the defaults should be read as production advice: a temperature of 0.2, six turns per request, 512 tokens per turn, and a 4-billion-parameter model are numbers chosen to keep the example short and legible.
The command line interface is a second name for the same module, so running it through a package runner and running the file directly execute identical code.
The manifest declares a test runner as a runtime dependency
The readme makes a clean claim: this project has no Python runtime dependency beyond the standard library, so you can run it directly with the script if you do not want to use the environment manager.
python mini_coding_agent.pyThe packaging metadata says otherwise. The runtime dependency list has exactly one entry, and it is a test runner, pinned to a version floor of nine.
So every installation of this package, whether from an index or from a checkout, pulls a test framework into the environment of an agent whose entire purpose is to have no third-party code in it. That is not a style objection. It means the thing the project is demonstrating, that you can read the whole implementation without installing anything, is false for anyone who installs it rather than cloning it.
The same file makes it worse. The development dependency group declares the same test runner again, with a lower floor, alongside a linter. So one file contains two different minimum versions of the same package, and the stricter one is in the wrong place.
Everything else about the packaging is tidy. The build requirements are bounded, the module list is explicit, and the console script points at the same module the readme tells you to run by filename. The dependency list is the only thing wrong, and it is wrong in a way that would be caught by a single sentence of review.
The tool protocol is two tag strings matched inside generated prose
The readme states the contract the model has to honour: it is expected to emit either a tool element or a final element, with the payload in between. Everything else follows from that.
This is not a structured-output schema the runtime validates. It is a convention the model has to follow in free text, and the agent has to find the tags and parse what is inside them. The readme is candid about the consequence: different models follow those instructions with different reliability, and if the model does not follow the format well, you should use a stronger instruction-following model.
Now put that next to the defaults. The default model is a 4-billion-parameter variant, and the same paragraph suggests a larger one if you have memory. Each turn is capped at 512 new tokens, and a request gets six turns. So the harness asks the smallest recommended model to reliably emit a correctly nested tag structure within 512 tokens, six times, and calls the default recommended.
Two settings do mitigate this and are worth naming. The sampling temperature is 0.2 and the nucleus cut-off is 0.9, both low, which is the right choice when you need a parser downstream to find structure rather than variety. And the backend is a plain text-generation endpoint, not a chat endpoint, so there is no provider-side tool calling doing the parsing for you.
The design is defensible for a teaching artefact. It is the first thing to change for real use.
A component exists to reuse a prompt cache the default backend does not have
One of the six components is prompt shape and cache reuse, and the readme gives its reason: a stable prompt prefix, kept separate from the changing request, transcript and memory, so repeated model calls can reuse the static parts efficiently.
The backend does not do that. The readme says the agent sends prompts to a local server's text-generation endpoint, and nothing anywhere in the file mentions prompt caching, prefix reuse or a context cache being enabled on that server.
So the separation between the stable prefix and the volatile parts is real and worth copying, but the benefit the readme attributes to it cannot occur with the project's own default setup. What remains is a structural discipline: the workspace facts, the instructions and the tool definitions are assembled once, and the request, transcript and memory are layered on top.
Which is exactly why the other components exist. Context reduction clips long outputs, deduplicates repeated reads and compresses older transcript entries. Memory keeps a full durable transcript alongside a smaller working summary. Delegation hands scoped subtasks to helpers that inherit enough context to operate within limits.
That is a coherent position: manage the context by hand because the model host will not do it for you. It is also a strong hint about where this harness came from, since the stable-prefix idea is designed for a hosted provider that bills less when the prefix repeats.
The dangerous mode is gated on trusting prompts, and prompts are not authored
Three approval modes, and the middle one deserves reading carefully.
Asking is the default and is described as recommended. Denying refuses risky actions outright. And the automatic mode allows risky actions automatically, including arbitrary command execution and file writes performed by the model, with the instruction to use it only with trusted prompts and trusted repositories.
Trusted prompts is the phrase that does not survive contact with how the agent works. The prompts in question are not something the operator writes and reviews. They are generated by a model, and that model has already read the workspace: the first component collects repository layout, instructions and git state before anything else happens. So the content of the repository is upstream of the prompt, and a repository you have not read is a repository whose text is already in the loop.
That is why the deny mode exists and why it is the one to reach for when pointing this at code you did not write. Read-only work, repository reconnaissance and anything on a machine you care about are all fine in deny mode; the agent still explores, still reads, still summarises.
What the file gets right is the shape of the control. There is one flag, the default is the careful one, and the dangerous one is named after what it does rather than hidden behind a config file. What it does not do is restate the risk in terms of repository content.
Sessions are written inside the workspace the agent is editing
The agent saves its sessions under the target workspace root, in a dot-directory named for the tool with a sessions folder inside it. One JSON file per session, named with a timestamp and a short hash.
Putting session state inside the workspace has an obvious benefit and an obvious cost. The benefit is that the history travels with the project, so a session on a laptop is the same session on a machine you ssh into. The cost is that running the agent inside a version-controlled repository writes untracked files into that repository, where they show up in status output, in diffs, and in a commit if nobody remembers to ignore them.
The second cost is quieter. The workspace is chosen by a flag whose default is the current directory, and the session store lives under whatever that resolves to. Change the directory and you are in a different session history, with no way to resume the conversation you had one directory up. There is no flag for a shared session root.
Inside the interactive loop there is a small set of commands that are handled by the harness itself rather than sent to the model as a task: help, a command that prints the distilled memory including the current task and tracked files, one that prints the path of the current session file, one that clears the history and the memory while leaving you in the loop, and two that exit.
Intercepting those locally rather than passing them to the model is the right call, and it is the kind of small correctness that separates a harness from a prompt.
Three names, one version anyone can cite, and a homepage that is an article
The same program has three identifiers. The repository is called one thing, the distribution published under a name that appends the backend, and the console command is a third spelling. Somebody following the readme's own advice to install it by name will not find this package.
The version is 0.1.0 in the packaging metadata, and the repository has no releases at all. So the number in the manifest is the only version anybody can cite, and there is no tag, no changelog and no release note to say what changed. The last push on record is 2026-04-07.
The declared homepage is not the project. It is a long-form article on a personal site explaining the components of a coding agent, and the readme links that article three separate times: once as a badge under the title, once as a bold line labelled as the detailed tutorial, and once more under the heading for the six components. Three links to one page is a reasonable way to make sure a reader finds the explanation, and it also means the readme's own documentation is one hop away from the code.
The readme also has an entire section whose entire content is a sentence telling you to look at another file in the repository. For a project whose value is showing you what an agent actually does, that is the section most likely to be wanted and the one that helps least.
Every generation knob is exposed and the host is a bare URL
The flag list is short and complete. It chooses the workspace directory, the model name, the server URL, the client timeout, resume behaviour, the approval mode, and five generation limits: turn count, output length per turn, temperature and nucleus sampling, plus the approval and resume pair again.
What is missing is as informative as what is present. There is no flag to supply your own system prompt, no flag to add a tool, no flag to remove one, and no flag to change the tag format the model is expected to emit. Those are all edits to the single module, which is consistent with the project's stated purpose and inconvenient for anyone who wants to run it rather than read it.
The server flag deserves a specific note. Its default is a loopback address and port for the local model server, and it is described as usually not needed. But it takes a URL and nothing else: there is no option for a token, no option for a certificate, and no option for a header. If you point it at a machine that is not your laptop, your prompts travel to that address in clear text, and along with them anything the agent read out of the workspace.
The timeout flag defaults to five minutes, which is generous for a local model and sensible for a first run that has to load weights into memory.
Editorial conclusion
mini-coding-agent is worth reading rather than adopting, and those are different activities. As a teaching artefact it is close to ideal: six components, one file, no framework, a prompt you can print, and a flag list that tells you every knob including the ones most harnesses hide. As something you point at a repository it is a different proposition, and the file is honest about the trade. Three things to weigh. Its stated optimisation target is readability rather than safety, and the mode that allows arbitrary command execution is one flag away from the default. Its tool protocol is two tag strings matched inside generated text rather than a schema the runtime enforces, and the default model is the smallest one the same document tells you to replace. And its packaging has a test runner declared as a runtime dependency of an agent that claims no runtime dependencies, which is the first thing to fix if you fork it. Read the code, copy the ideas, and use a real agent for the work.
Frequently asked questions
What is mini-coding-agent?
A single-file Python agent harness written to explain how coding agents work. It has six components: workspace snapshot collection, a stable prompt prefix kept separate from the volatile parts, named tools with checked inputs and approval gates, context clipping and deduplication, a durable transcript alongside a smaller working memory, and bounded subagent delegation. The model backend is Ollama.
What does mini-coding-agent need before it runs?
Python 3.10 or later, Ollama installed, and a model pulled locally. The default is qwen3.5:4b, and the readme suggests a larger Qwen 3.5 variant if you have memory, and a stronger instruction-following model if the tag format is not followed reliably. The environment manager is optional.
How do I control risky actions in mini-coding-agent?
There are three approval modes. Asking is the default and is described as recommended, denying refuses risky actions outright, and the automatic mode allows risky actions including arbitrary command execution and file writes by the model. The readme says to use the automatic mode only with trusted prompts and trusted repositories.
Where does mini-coding-agent keep its sessions?
Under the target workspace root, in a dot-directory named for the tool with a sessions folder inside, one JSON file per session named with a timestamp and a short hash. You can resume the most recent session or a specific one by id, and an interactive command prints the path of the current session file while another prints the distilled memory.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/rasbt-mini-coding-agent)Star history chart for your README
[](https://hysenlabs.com/projects/rasbt-mini-coding-agent)Was this useful?