I was scrolling through my GitHub stars looking for something to write about and stopped on this one again. mini-swe-agent is the kind of project I like: it takes something everyone assumes needs a huge framework (an AI coding agent) and does it in about 100 lines of Python.

It's built by the Princeton and Stanford team behind SWE-bench and SWE-agent, the projects that kickstarted a lot of the coding agent hype in 2024. Their pitch with mini is simple: what if the agent was 100x simpler and still worked nearly as well? Turns out it scores over 74% on SWE-bench verified, which is genuinely impressive for something this small.

The core idea

Most agent frameworks give the model a set of tools (file editors, search, structured function calls) and a stateful environment to track. mini throws almost all of that away. The agent only has one tool: bash. No tool-calling interface, no custom file editing API, nothing fancy.

Every action runs through subprocess.run, completely independent from the previous one. No persistent shell session to manage. This sounds like a limitation, but it's actually the opposite. It means you can swap subprocess.run for docker exec and suddenly your agent runs in a sandbox. It means any model works, even ones that don't support tool calling, because the agent just asks the LM to write a shell command and runs it.

The history is also completely linear: every step just appends to the message list. What you see in the trajectory is exactly what gets sent to the model. No separate internal state to reconstruct, no surprises when you're debugging a run that went wrong.

Trying it out

pip install uv && uvx mini-swe-agent
# or
pip install mini-swe-agent
mini

That's the whole setup. It supports local environments, Docker, Podman, and a few sandboxing options, and it works with any model through litellm, openrouter or portkey.

There's also a Python API if you want to embed it directly instead of using the CLI:

agent = DefaultAgent(
    LitellmModel(model_name="..."),
    LocalEnvironment(),
)
agent.run("Write a sudoku game")

Why it's worth starring

If you've ever looked at a big agent framework and felt like 90% of it was ceremony you didn't need, this is a nice antidote. It's small enough to actually read end to end in one sitting (the agent class itself is genuinely about 100 lines), which makes it a great base if you want to build your own thing on top instead of fighting someone else's abstractions.

Companies like Meta, NVIDIA and IBM are apparently already using it, so it's not just a toy. Worth a star if you're curious how far a minimal agent loop can actually get you.