minion: a single-file coding agent built to keep context small for local models
A tiny single-file coding agent for self-hosted models (llama.cpp / vLLM / SGLang).
At a glance
- What is it?
- minion is an MIT single-file coding agent designed to avoid context bloat, sending about 625 tokens on a bare greeting where many frameworks use tens of thousands. It targets self-hosted models served through llama.cpp, vLLM or SGLang via an OpenAI-compatible endpoint.
- Who is it for?
- Use minion if you run self-hosted models through llama.cpp, vLLM or SGLang and want a real coding agent whose context footprint is tiny, about 625 tokens on a greeting rather than the tens of thousands larger frameworks use, keeping your model's fast, high-attention context for your actual code. It is the wrong choice if you want a broad feature set, many built-in tools or a plugin ecosystem, since it is deliberately a single file with five tools.
- Can I use it commercially?
- Yes. MIT 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 55 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 17, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
A coding agent that does not waste your context
minion is a single-file coding agent built around one goal: keeping context small. The README's complaint is concrete, many agent frameworks use 20,000 to 50,000-plus tokens when you have just said hey, because they load a lot of features and tool schemas into the model's context. minion is a purpose-built agent aimed at removing and keeping out that context bloat.
The user is someone running coding agents on local, self-hosted models, where context is scarce and precious. The README explains why it matters for local models specifically: that first stretch of context is your fastest context and where the model's attention is strongest, so wasting it on framework overhead costs both speed and quality on hardware where you cannot spare either.
The distinguishing design is minimalism as a hard constraint. minion is a single file, and on a bare `hey` the entire prompt it sends is about 625 tokens: roughly 98 for the system prompt, 475 for five tool schemas, one for the word itself, and about 50 for chat-template framing. Publishing that token budget, and being honest that the variance is in how each server's chat template wraps tools, is exactly the transparency a local-model user needs. It is MIT licensed.
Small by construction, for local serving
The mechanism is subtraction. Where feature-rich frameworks load many tools and elaborate instructions, minion ships five tool functions and a short system prompt, which is why its baseline prompt is around 625 tokens rather than tens of thousands. The README's breakdown, system prompt, tool schemas, the message, and chat-template framing, accounts for the whole budget, so there is no hidden overhead.
That matters most on local models. The README's argument is that the first chunk of context is the fastest and the highest-attention, so an agent that keeps its own footprint tiny leaves that valuable context for your actual code and instructions. On a cloud API the waste is money over time; on a local model it is also speed and attention you cannot get back, which is why minion targets the self-hosted case.
Being a single file is part of the philosophy, not just packaging: there is no framework to load, no plugin system pulling in schemas, and the whole agent is auditable in one place. The README is even precise that the real total varies by server because Qwen/Hermes, llama.cpp and OpenAI each wrap the tool section differently, which is the kind of detail only someone who actually measured it would include.
Running it against a local model
minion talks to any OpenAI-compatible endpoint, so it works with a locally served model. The README's basic setup installs the OpenAI client and points minion at your local server through environment variables:
pip install openai
export MINION_BASE_URL=http://localhost:8080/v1
export MINION_MODEL=your-model-name
export MINION_API_KEY=sk-noop
python minion.pyThe README notes the API key can be any string because local servers ignore it, which is exactly right for llama.cpp, vLLM or SGLang serving an OpenAI-compatible API. There is also an editable install path, `pip install -e .`, for using it as a package.
Because it points at a base URL, minion is server-agnostic: the README's examples cover self-hosted models through llama.cpp, vLLM and SGLang, and it can equally sit in front of a proxy like LiteLLM if you want to route to a hosted model. The single-file design means running it is genuinely just `python minion.py` against your endpoint, which is the low-friction experience a local-model tinkerer wants, without a framework to configure first.
The limitations: minimal by design means fewer features
The honest limitation is the direct consequence of the philosophy: minion is deliberately minimal, so it has five tools and a small system prompt, not the broad feature set of a large agent framework. If you want many built-in tools, elaborate planning scaffolding or a plugin ecosystem, minion does not have them, on purpose. The thing that makes it context-light is the same thing that makes it feature-light.
That trade is right for its target, local models with tight context, and wrong for someone who wants a maximal agent on a large-context cloud model where the overhead does not hurt. minion is not trying to compete on features; it is competing on footprint, and a user should pick it because small context matters to them, not expecting parity with a heavyweight framework.
Being a single file also means its capabilities are bounded by what fits that design. Extending it is editing the file rather than installing plugins, which is simple and auditable but means growth is manual. The README's own honesty that the token total varies by server is also a reminder that the exact footprint depends on your model's chat template, so the 625-token figure is a representative baseline, not a guarantee for every server.
Against a full agent framework or raw API calls
The alternatives are a full-featured agent framework and raw, hand-written API calls. A full framework gives many tools, planning and integrations but pays the context cost minion is built to avoid, tens of thousands of tokens before you have done anything, which is fine on a large cloud model and painful on a local one. Raw API calls have no overhead but also no agent loop, no tools and no structure; you build everything yourself.
minion's difference is that it provides a working coding agent, a tool loop with five functions, at a fraction of the context cost, so a local model keeps its fast, high-attention context for your actual task. The cost is the small feature set. Choose a full framework when you run large-context cloud models and want maximum capability. Choose raw API calls when you want total control and no agent structure. Choose minion when you self-host models, context is scarce, and you want a real coding agent whose own footprint is around 625 tokens rather than 50,000, keeping your best context for your code.
MIT, single-file, and where to start
minion is MIT and a single file, which together make it maximally hackable: you can read the entire agent, understand exactly what it puts in context, and edit it directly, with no framework internals to learn. For a tool whose whole selling point is a small, known footprint, that auditability is essential, since you can verify the token budget yourself rather than trust it.
There is no real upgrade machinery: updating is pulling a newer version of the file, and because it depends only on the OpenAI client and an OpenAI-compatible endpoint, there is little to break underneath it. That minimal dependency surface is consistent with the minimalism throughout.
The concrete first step is to run it against your own local server and measure: install the OpenAI client, set `MINION_BASE_URL`, `MINION_MODEL` and a throwaway `MINION_API_KEY`, run `python minion.py`, and confirm on a bare greeting that the context sent is in the ballpark of the README's 625-token figure for your model's chat template. Since the exact total varies by how your server wraps tools, that check tells you the real footprint on your setup, which is the whole reason to choose minion for a context-constrained local model.
Editorial conclusion
Use minion if you run self-hosted models through llama.cpp, vLLM or SGLang and want a real coding agent whose context footprint is tiny, about 625 tokens on a greeting rather than the tens of thousands larger frameworks use, keeping your model's fast, high-attention context for your actual code. It is the wrong choice if you want a broad feature set, many built-in tools or a plugin ecosystem, since it is deliberately a single file with five tools. Start by pointing it at your local server: install the OpenAI client, set MINION_BASE_URL, MINION_MODEL and any MINION_API_KEY, run python minion.py, and verify on a bare greeting that the context sent matches the README's roughly 625-token baseline for your model's chat template.
Frequently asked questions
Why does minion focus on small context?
The README says many agent frameworks use 20,000 to 50,000+ tokens on a bare greeting, and that the first stretch of context is the fastest and highest-attention. On local models, where context is scarce, minion keeps its own footprint to about 625 tokens so your code gets that valuable context.
What models does minion work with?
The README targets self-hosted models served through llama.cpp, vLLM or SGLang via an OpenAI-compatible endpoint. You point minion at the base URL with MINION_BASE_URL and set MINION_MODEL; the API key can be any string since local servers ignore it.
How do I run minion?
The README installs the OpenAI client (pip install openai), sets MINION_BASE_URL, MINION_MODEL and MINION_API_KEY environment variables pointing at your local server, and runs python minion.py. There is also an editable install via pip install -e .
Community notes