# mini-swe-agent: a 100-line coding agent you can read in one sitting

> mini-swe-agent replaces the usual agent scaffold with bash and a linear message history. It is a good fit when you want a baseline you can debug, and a poor fit when you want built-in tools and a polished UI.

**SWE-agent/mini-swe-agent** — 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!

- Repository: https://github.com/SWE-agent/mini-swe-agent
- Website: https://mini-swe-agent.com
- Stars: 7,717 · Forks: 1,042
- Language: Python
- License: MIT
- Published: 2026-09-10 · Updated: 2026-09-10 · Language: en
- Canonical page: https://hysenlabs.com/projects/swe-agent-mini-swe-agent

## What mini-swe-agent solves, and who it is for

Most coding agents ship as frameworks. They define a tool schema, a history processor, a shell abstraction and a configuration format, and the model is asked to work inside that structure. The mini-swe-agent authors argue the opposite: as language models have become more capable, much of that scaffolding is unnecessary. The project's own framing is the question "What if our agent was 100x simpler, and still worked nearly as well?"

The target reader is not someone who wants a chat interface for their repository. It is an engineer or researcher who wants to see the whole loop, change it, and trust it. The README lists the use cases directly: a quick command line tool that works locally, an agent with a very simple control flow, faster sandboxing and benchmark evaluation, and fine-tuning or reinforcement learning work where you do not want to overfit to a particular scaffold.

The project reports a score above 74% on SWE-bench verified, and the README notes it is used by Meta, NVIDIA, Essential AI, IBM, Nebius, Anyscale, Princeton University and Stanford University. Those are adoption claims from the README, not independent measurements. The more useful signal for a prospective user is structural: the agent class is roughly 100 lines of Python, and the repository is small enough to read before you run it.

## Bash only, linear history, and subprocess per action

Three design decisions define the mechanism, and each one has a cost.

First, the agent has no tools other than bash. It does not use the model's tool-calling interface at all. The README states this explicitly: instead of implementing custom tools for every specific thing the agent might want to do, the focus is fully on the model using the shell. The practical consequence is that the agent can run with any model that can produce text, which is why litellm, openrouter and portkey support matter. The trade-off is that anything you want the agent to do reliably has to be expressible as a shell command, and the model has to know the command. There is no schema telling it what a pull request tool accepts.

Second, the history is completely linear. Every step appends to the message list that is passed to the model on the next turn. The README points out that there is therefore no difference between the trajectory and the messages sent to the model, which makes debugging and fine-tuning straightforward. If you have used an agent with a separate history processor that summarizes or prunes turns, this is the opposite approach. Long sessions grow the context until something else has to handle it.

Third, actions execute through subprocess.run, and every action is independent. There is no persistent shell session holding state between steps. The README calls this a big deal for stability and for sandboxing, because switching subprocess.run for docker exec is the whole change. The cost is real: an exported environment variable, a changed working directory, or an activated virtualenv does not survive into the next command unless the model re-establishes it each time. The documentation addresses this in a FAQ entry titled "Why no shell session".

The run script and environment and model layers are separate files, so you can replace one without touching the others. That separation is what makes the deployment targets possible.

## Installing mini-swe-agent and running it once

The package is published on PyPI as mini-swe-agent, and pyproject.toml requires Python 3.10 or newer. The README points to the documentation site for usage; the install path is the standard pip one. The repository also defines optional dependency groups named full, modal and dev, so the full set of extras is installed as mini-swe-agent[full].

```bash
pip install mini-swe-agent
```

After installation, the README links to the file src/minisweagent/run/hello_world.py, which is the run script the repository ships, and the CLI documentation lives under /latest/usage/mini/ on the project site. That file is the entry point to read first; the README does not print a command line for it, so open the file and the CLI documentation page before running anything.

Expect the agent to start issuing bash commands and printing the model's responses as it works. Because the agent uses litellm for model access, you need a model name and credentials available in the environment before the first run succeeds; the README does not spell out the exact environment variable names, so check the documentation site for the model configuration page rather than guessing.

If you want the sandboxed path instead of local execution, the README lists local environments, docker/podman, singularity/apptainer, bubblewrap and contree as supported deployment targets, and pyproject.toml exposes a modal extra alongside a swe-rex dependency in the full group. Those are the backends to read about before you point the agent at a repository you care about.

One warning worth repeating from the README: this is mini-swe-agent v2, and there is a migration guide at /latest/advanced/v2_migration/. If you have existing scripts written against the v1 branch, they will need review.

## Where the minimal design becomes the wrong tool

The absence of a persistent shell is the sharpest limitation. Any workflow that depends on accumulated shell state, such as a long-running server started in one step and queried in the next, has to be restructured so each command is self-contained. Agents with a stateful session handle that pattern naturally. Here you are trading that convenience for sandbox portability and for the ability to scale actions independently, which the README presents as the deliberate choice.

Context growth is the second constraint. A linear history that only appends means every step carries the full prior conversation. There is no built-in summarization step in the agent loop, so a long debugging session on a large repository will consume context steadily. The README frames the linear history as an advantage for debugging and fine-tuning, and it is, but it is also the reason the agent is better suited to bounded tasks than to open-ended sessions.

The third issue is scope. The README is candid that some agents are "overfitted research artifacts" and others are "UI-heavy frontend monsters", and that mini wants to be a hackable tool. If what you actually want is a curated set of tools with their own interfaces, or different history processors, the README says to use SWE-agent instead. That is not a knock on mini; it is the project telling you where its boundary is.

Finally, the classifier in pyproject.toml marks the development status as Alpha. The version numbers are past 2.0 and releases are frequent, but the project itself is not claiming production stability.

## mini-swe-agent versus SWE-agent and versus a full CLI assistant

The most direct alternative is SWE-agent, from the same authors. The README's own guidance is that mini-swe-agent should be your default choice, and SWE-agent is for experimenting with different tool sets that each have their own interface, or with different history processors. The difference is architectural, not cosmetic: SWE-agent keeps the tool-and-interface layer that mini removed, so it gives you more control over how the model interacts with the system at the cost of a larger surface to understand. Both share the SWE-bench performance work and a trajectory browser.

A second comparison point is a general purpose CLI coding assistant with a rich built-in tool set. The README claims mini-swe-agent starts much faster than Claude Code and that it beats Claude Code and Codex on DeepSWE, citing an external blog post. Treat those as the project's claims. The structural difference is what matters for a decision: a tool-rich assistant decides for you which capabilities exist and how they are invoked, while mini-swe-agent pushes that decision into the shell and into the prompt. If you want the model to figure out how to open a pull request rather than having a pull request tool, mini is the closer match. If you want the tool to exist and behave consistently, it is not.

For benchmark and research work, the relevant alternative is not another agent but a heavier harness. The README positions mini as a baseline system and as a way to put the language model, rather than the scaffold, at the center of attention, and points to the bash-only SWE-bench leaderboard as the result of that positioning.

## Maintenance, upgrades and the MIT licence

The repository is not archived. The last push was on 2026-09-07, and the most recent release listed is v2.4.6 from 2026-07-23, preceded by v2.4.5 on 2026-07-06 and v2.4.4 on 2026-07-02. That is a steady release cadence over the period covered by the release list, and the gap between the last release and the last push suggests work continues between tagged versions.

The upgrade cost is concentrated in the v2 transition. The README carries a warning that this is mini-swe-agent v2 and links a migration guide at /latest/advanced/v2_migration/, with the previous version living on the v1 branch. Anyone with v1 scripts should read that guide before upgrading rather than assuming compatibility. Within v2, the dependency pins are worth noting: pyproject.toml requires litellm >= 1.75.5 while excluding 1.82.7 and 1.82.8, and excludes openai 1.100.0 and 1.100.1, with the former annotated as a security exclusion. Those exclusions mean your resolver may need to move other packages to satisfy them.

The licence is MIT, declared both in the classifiers as "License :: OSI Approved :: MIT License" and via a LICENSE.md file referenced from pyproject.toml. MIT is permissive and imposes no copyleft obligation on your own code. That is a statement about the licence text, not legal advice; if you are redistributing the package or bundling it into a product, have your own counsel review the file.

## Conclusion

Adopt mini-swe-agent if you want a small, readable agent for local command line work, benchmark harnesses, or fine-tuning experiments where the scaffold should not get in the way. Do not adopt it if you need a curated tool set, a stateful shell, or a graphical interface out of the box; SWE-agent covers those cases. Before committing, verify that your model is reachable through litellm, confirm which sandbox backend you will run in, and check the v2 migration guide if you used the v1 branch.

## FAQ

### What is mini-swe-agent?

It is a minimal AI software engineering agent from the team behind SWE-bench and SWE-agent. The agent class is roughly 100 lines of Python, it uses bash as its only tool, and the README reports a score above 74% on SWE-bench verified.

### How do I install mini-swe-agent?

The package is on PyPI as mini-swe-agent and pyproject.toml requires Python 3.10 or newer, so pip install mini-swe-agent is the install step. Optional extras are grouped as full, modal and dev.

### How do I use mini-swe-agent?

The README links a run script at src/minisweagent/run/hello_world.py and points to the CLI documentation under /latest/usage/mini/. Model access goes through litellm, so credentials and a model name must be configured before the first run.

### Should I use mini-swe-agent or SWE-agent?

The README says to consider mini-swe-agent your default choice, and to use SWE-agent when you want to experiment with different tool sets that each have their own interface, or with different history processors. Both share SWE-bench performance work and a trajectory browser.

### What is an SWE agent?

The README describes SWE-agent as the project that jump-started AI agent development in 2024, built by the Princeton and Stanford team behind SWE-bench. It placed emphasis on tools and special interfaces for the agent, which mini-swe-agent later removed.

## Sources

- [License: MIT](https://github.com/SWE-agent/mini-swe-agent/blob/main/LICENSE)
- [Project website](https://mini-swe-agent.com)
- [README](https://github.com/SWE-agent/mini-swe-agent/blob/main/README.md)
- [Releases](https://github.com/SWE-agent/mini-swe-agent/releases)
- [SWE-agent/mini-swe-agent on GitHub](https://github.com/SWE-agent/mini-swe-agent)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/swe-agent-mini-swe-agent