mini-swe-agent: a bash-only coding agent in roughly 100 lines
The 100 line AI agent that solves GitHub issues or helps you in your command line. Radically simple, no huge configs, no giant monorepo—but scores >74% on SWE-bench verified!
At a glance
- What is it?
- mini-swe-agent replaces the tool-heavy scaffold of SWE-agent with a single bash action loop built on subprocess.run. It is aimed at people who want a readable baseline for benchmarks, fine-tuning, or daily command line work, and the README puts its SWE-bench verified score above 74 percent.
- Who is it for?
- Adopt mini-swe-agent if you want a baseline you can read end to end, run against any litellm-compatible model, and swap into a sandbox by replacing subprocess.run with docker exec. Do not adopt it if your work depends on custom tool interfaces or non-linear history processing, which is what the full SWE-agent exists for.
- 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 1 day 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 mini-swe-agent was built to remove
SWE-agent, released in 2024 by the same Princeton and Stanford team, treated the agent scaffold as the product. Tools had interfaces, history had processors, and the agent had opinions about how a language model should talk to a shell. mini-swe-agent starts from the opposite premise, stated in the README as a question: what if the agent were 100x simpler and still worked nearly as well. The answer is a loop with no tools other than bash. There is no tool-calling interface to satisfy, so the model can be anything that produces text. The target user is not someone who wants a polished assistant. It is an engineer who needs to read the entire control flow in one sitting, debug what the model was actually prompted with, or use the agent as a fixed scaffold while varying the model underneath. The README names fine-tuning and reinforcement learning as the cases where that matters most, because a minimal scaffold is harder to overfit to.
One bash action per step, executed with subprocess.run
The mechanism is deliberately flat. Each step appends to a message list, the model returns a bash command, the command runs, and its output is appended back. The README describes the history as completely linear, meaning the trajectory and the messages sent to the model are the same object. That is a debugging property, not a performance one, and it is the main reason the code stays small. Actions execute through subprocess.run rather than a persistent shell session. Every action is therefore independent: no exported variables, no working directory carried over from the previous step, no state to corrupt. The README calls this a big deal for stability and points to an FAQ entry titled why no shell session. The trade-off is real. A command that depends on state from an earlier command has to re-establish it, and the model has to learn to write self-contained commands. In exchange, moving execution into a sandbox becomes a substitution: the README says you can literally switch subprocess.run for docker exec. The agent class is around 100 lines; the environment, model, and run script add more. The README points to src/minisweagent/agents/default.py, src/minisweagent/environments/local.py, src/minisweagent/models/litellm_model.py, and src/minisweagent/run/hello_world.py as the files that make up the core.
Installing from PyPI and picking an environment backend
The package is published on PyPI as mini-swe-agent, so installation follows the usual pip path. The README does not reproduce a full command sequence in the portion available here, so treat the exact invocation as something to confirm against the docs site at mini-swe-agent.com/latest rather than something this article can assert. What the README does establish is the shape of the configuration surface. Model access goes through litellm, with openrouter and portkey named as additional routes, and support listed for both /completion and /response endpoints as well as interleaved thinking. Execution backends named in the README are local environments, docker, podman, singularity, apptainer, bubblewrap (spelled bublewrap in the README), and contree. Those two axes, model and environment, are the ones you configure. There is no giant config file to learn, which is the stated design goal, but it also means the documentation site carries the weight that a config schema would otherwise carry. The v2 migration guide is linked from a warning at the top of the README, and the v1 code lives on a separate branch. If you are starting fresh, v2 is the version to read.
Where the bash-only design stops being an advantage
The README is candid that the full SWE-agent exists for cases mini does not cover. If you want to experiment with different sets of tools that each have their own interface, or with different history processors, mini-swe-agent is the wrong tool and SWE-agent is the right one. That is not a small caveat. Any workflow where the agent must call a structured API, produce a validated artifact, or maintain a non-linear conversation history will fight the design. The stateless execution model has a second cost: long multi-step tasks where each command depends on the last become verbose, because the model must reconstruct context in every command. And the 100-line claim applies to the agent class specifically. The environment, model wrapper, and run script are additional code, so the honest reading is a small core rather than a small program. The README also notes that mini-swe-agent is now at v2 with a migration guide, which means anyone on v1 has a real upgrade to perform rather than a drop-in patch.
How it differs from the original SWE-agent
SWE-agent and mini-swe-agent share a lineage, a benchmark target, and a trajectory browser, according to the README. The difference is where the intelligence is assumed to live. SWE-agent places emphasis on tools and special interfaces, an approach that made sense in 2024 when language models were less capable of driving a shell directly. mini-swe-agent bets that the model no longer needs that scaffolding, so instead of implementing a tool for opening a pull request, you tell the model to figure it out with bash. The practical consequences run in both directions. You lose the ability to constrain what the agent can do through a typed tool surface, which matters if you need auditability or a narrow action space. You gain portability, because anything that can run bash can host the agent, and you gain a trajectory that is identical to the prompt, which matters for fine-tuning and for reading back what happened. The README frames mini as the default choice and SWE-agent as the escape hatch for tool and history-processor experiments.
Maintenance, licence, and what the release cadence implies
The project is MIT licensed, which permits commercial use, modification, and redistribution provided the copyright notice and permission notice are preserved. That is the standard permissive arrangement, and it is compatible with the kind of internal deployment the README describes. It is not legal advice; check the LICENSE file in the repository for the binding text. On maintenance, the repository is not archived, the default branch is main, and the most recent push recorded is 2026-09-07. Releases v2.4.4, v2.4.5, and v2.4.6 landed between 2026-07-02 and 2026-07-23, which is a cadence of roughly one release every two to three weeks across that window. For an agent that shells out to language models, that cadence matters more than usual, because provider APIs and endpoint behaviours change. The upgrade cost is bounded by the small surface area: model routing through litellm and the environment backend are where breakage is most likely. The v2 migration guide exists precisely because a version boundary required code changes, so pin your version and read the guide before moving.
What to verify before you depend on it
The README claims a score above 74 percent on SWE-bench verified. That number is attached to a specific model and a specific harness configuration, and the README does not, in the material available here, spell out which. Reproduce it on the model you actually intend to use before you plan around it. Second, decide your environment backend first, because local, docker, podman, apptainer, bubblewrap, and contree are not interchangeable in operational terms, and the sandboxing story is the reason many teams adopt this over a stateful-shell agent. Third, read the why no shell session FAQ entry before writing prompts, since a model that assumes persistent state will produce commands that fail. Fourth, check the v2 migration guide if you have any v1 code, and note that v1 lives on a separate branch. The project is small enough that all four checks are an afternoon, which is itself the argument for it.
Editorial conclusion
Adopt mini-swe-agent if you want a baseline you can read end to end, run against any litellm-compatible model, and swap into a sandbox by replacing subprocess.run with docker exec. Do not adopt it if your work depends on custom tool interfaces or non-linear history processing, which is what the full SWE-agent exists for. Before committing, read the v2 migration guide, confirm which environment backend you will use, and reproduce the SWE-bench number on your own model rather than trusting the README figure.
Community notes