mini-swe-agent — Summary

mini-swe-agent is a deliberately minimal Python coding agent from the Princeton/Stanford SWE-bench team that answers the question: "What if our agent was 100x simpler, and still worked nearly as well?" The core DefaultAgent class is ~130 lines of Python, uses only bash as a tool (no file-specific tools), executes each action with subprocess.run (stateless — no persistent shell session), maintains a completely linear message history, and supports all LLMs via litellm. Despite this radical simplicity, it scores >74% on SWE-bench verified with Gemini 3 Pro. It ships a CLI (mini), multiple sandboxed execution environments (Docker, Singularity, bubblewrap, contree), a trajectory browser UI (Textual TUI), and batch evaluation mode. The intentional minimalism serves two purposes: (1) a clean research baseline that isolates LLM capability from agent scaffold; (2) a hackable daily-use tool.

Compared to seeds: no seed framework approaches this level of intentional minimalism. The closest is agent-os (zero-primitive scaffold), but mini-swe-agent is a fully functional agent with 74% SWE-bench performance in ~100 lines. The architectural insight — single bash tool + stateless subprocess execution + linear history — is unique in the entire corpus.

mini-swe-agent — Overview

Origin

Created by the Princeton & Stanford team behind SWE-bench and SWE-agent. Repository: SWE-agent/mini-swe-agent. MIT license. ~4526 GitHub stars. Actively maintained (last push: 2026-05-25).

Philosophy

"What if our agent was 100x simpler, and still worked nearly as well?"

Key design decisions (from README):

"Does not have any tools other than bash — it doesn't even need to use the tool-calling interface of the LMs."

"Executes actions with subprocess.run — every action is completely independent (as opposed to keeping a stateful shell session running). This makes it trivial to execute the actions in sandboxes."

"Has a completely linear history — every step of the agent just appends to the messages and that's it. So there's no difference between the trajectory and the messages that you pass on to the LM. Great for debugging & fine-tuning."

The Core Insight

"As LMs have become more capable, a lot of [the tools and special interfaces] is not needed at all to build a useful agent!"

The agent removes complexity from the scaffold and places the cognitive burden entirely on the LLM. This makes it:

• Easier to debug (linear history = perfect observability)
• Easier to fine-tune (trajectory = training data in the exact format needed)
• Easier to sandbox (stateless subprocess = just replace subprocess.run with docker exec)
• Easier to reason about (no state machine, no tool registry, no history processors)

Manifesto quote

"Some agents are overfitted research artifacts. Others are UI-heavy frontend monsters. The mini agent wants to be a hackable tool, not a black box."

LOC Count

• DefaultAgent class: ~130 lines (src/minisweagent/agents/default.py)
• LocalEnvironment: ~100 lines
• LitellmModel: ~100 lines
• hello_world.py run script: ~50 lines
• Total core: ~400 lines of Python

mini-swe-agent — Architecture

Distribution & Install

• pip install mini-swe-agent
• Binary: mini (CLI)
• Also available for batch evaluation via Python bindings

Required Runtime

• Python (version from pyproject.toml)
• litellm (for universal LLM provider support)
• Optional sandbox environments:
  • Docker / Podman
  • Singularity / Apptainer
  • bubblewrap
  • contree

Source Structure

src/minisweagent/
├── agents/
│   └── default.py          # DefaultAgent class (~130 lines) — THE core
├── environments/
│   └── local.py            # LocalEnvironment class
│   (+ docker, singularity, bubblewrap, contree environments)
├── models/
│   └── litellm_model.py    # LitellmModel class
├── run/
│   └── hello_world.py      # CLI entry point script
├── config/
│   ├── default.yaml        # Default config with system + instance templates
│   ├── mini.yaml           # Interactive CLI config
│   └── benchmarks/         # SWE-bench evaluation configs
└── utils/

Agent Simplicity Architecture

DefaultAgent
├── messages: list[dict]     # Linear history — only data structure
├── model: Model             # Any litellm-supported model
├── env: Environment         # Local or sandboxed
├── config: AgentConfig
│   ├── system_template      # Jinja2 template for system message
│   ├── instance_template    # Jinja2 template for first user message
│   ├── step_limit           # Hard stop
│   └── cost_limit           # Cost-based stop
└── run() → step() → query() + execute_actions()

Tool Surface: Bash Only

The agent has exactly ONE tool: bash. No file-read tool, no search tool, no diff tool — just bash. The model must figure out cat, grep, sed, etc. on its own.

Python SDK

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

mini-swe-agent — Components

Core Classes (minimal by design)

DefaultAgent Methods

Execution Environments

Config Files (Jinja2 YAML)

CLI: mini

The mini CLI binary provides interactive use with the default configuration. A swebench mode exists for batch evaluation.

Trajectory Browser

A Textual (Python TUI) browser for viewing agent trajectories — shows messages, tool calls, costs, and outcomes. Mentioned as a key feature alongside the CLI.

mini-swe-agent — Uniqueness & Positioning

Differs from Seeds

No seed framework approaches this level of intentional minimalism. The closest is agent-os (zero primitives, markdown scaffolding) — but agent-os has no agent execution capability at all. mini-swe-agent is the only framework in the entire corpus that treats radical simplicity as the explicit engineering thesis and demonstrates it achieves near-state-of-the-art benchmark performance (>74% SWE-bench verified). The key deltas from all seeds: (1) single bash tool — no file-read, no diff, no search tools; (2) stateless subprocess execution — no persistent shell session; (3) linear message history — the trajectory IS the message history, no abstraction layer; (4) designed to be a fine-tuning data source — the trajectory format is training-ready; (5) multiple sandbox backends interchangeable via a single code change.

Positioning

The canonical "what is the minimum viable coding agent?" reference implementation. Used by Meta, NVIDIA, Essential AI, IBM, and universities as a baseline for agent research. Not primarily a production tool — it is a research artifact and a hackable starting point.

Key Differentiators

1. ~130 lines for the agent class — intentionally minimal, documented as a design goal
2. Only bash — no tool registry; forces LLM to use shell creatively
3. Stateless subprocess — each command in a fresh subshell; makes sandboxing trivial
4. 74% SWE-bench verified — competitive with much more complex agents
5. Linear trajectory = fine-tuning data — trajectory format is training-ready
6. Multiple sandbox environments — local, Docker, Singularity, bwrap, contree

Observable Failure Modes

• No persistence: cd doesn't persist — agents must prefix each command; this confuses models occasionally
• Context window growth: no compaction; long sessions may exceed context limits
• Single model limitation: no expert escalation or multi-model routing
• No recovery mechanism: if the agent writes bad code and tests fail, there's no rollback
• Intentional scope: not designed for interactive coding sessions — best for well-defined issue-fixing tasks