mini-SWE-agent

The minimal successor to SWE-agent — a ~100-line core that autonomously resolves GitHub issues, as performant but far simpler

Website ↗ Repository ↗ Docs ↗

v2.4.62026-07-23PythonMIT

#github-issues #swe-bench #autonomous #python

6.0k Completely free Open source

Doc version 1.0 · Updated June 28, 2026

Related tools

SWE-agentMaintenance only

Autonomous SWE

Overview

mini-SWE-agent is the streamlined successor to SWE-agent.
It keeps the same idea — let a model read, edit, and run code to fix a GitHub issue — but strips the agent loop down to roughly 100 lines: no special tools, just shell commands.
It’s simpler to read, hack on, and deploy while staying competitive on SWE-bench.

flowchart LR
  task[task] --> agent[mini-SWE-agent]
  agent -->|bash command| shell[(shell)]
  shell -->|output| agent
  agent --> done([submit])

The Code samples tab shows two ways to use it — the CLI and the Python binding; pick from the selector to compare.

When to use it

Prefer mini-SWE-agent over SWE-agent for new work: it’s the actively developed path, and its tiny core makes it easy to understand and customize.

Example

CLI · mini

When to use

Reach for the CLI when you want to run the agent straight from a terminal.

How it flows

The agent proposes a bash command, runs it in your shell, observes the output, and iterates until the task is done.

Structure

flowchart LR
  task[task] --> agent[mini]
  agent -->|bash command| shell[(your shell)]
  shell -->|output| agent
  agent --> done([submit])

pip install mini-swe-agent

# Interactive, in the current repo:
mini

# Or a one-off task with an explicit model:
mini -m claude-opus-4-8 -t "Fix the failing test in tests/test_parser.py"

When to use

Reach for the Python binding when you want to embed the agent in your own program.

How it flows

DefaultAgent ties the model, environment, and config together, runs the loop, and returns the exit_status and submission when it ends.

Structure

flowchart LR
  model[LitellmTextbasedModel] --> agent[DefaultAgent]
  env[LocalEnvironment] --> agent
  agent -->|run task| loop[bash loop]

import yaml
from minisweagent import package_dir
from minisweagent.agents.default import DefaultAgent
from minisweagent.environments.local import LocalEnvironment
from minisweagent.models.litellm_textbased_model import LitellmTextbasedModel

config = yaml.safe_load((package_dir / "config" / "default.yaml").read_text())["agent"]

# The default config asks for a ```mswea_bash_command fence, so pair it
# with the text-based model. MODEL is routed through LiteLLM.
agent = DefaultAgent(
    LitellmTextbasedModel(model_name="anthropic/claude-opus-4-8"),
    LocalEnvironment(),
    **config,
)
result = agent.run("Print the result of 2 + 2, then submit.")
print(result["exit_status"], result.get("submission", ""))

For a runnable build, see mini-swe-agent_1 in the Implementation tab — use a capable model.

Example

mini-SWE-agent — a shell-only coding agent

A real, runnable mini-project. Download it and run with Docker.

View samples/mini-swe-agent_1 on GitHub ↗

June 28, 2026

mini-SWE-agent — a shell-only coding agent

A minimal mini-SWE-agent binding: a DefaultAgent drives a LocalEnvironment with a text-based LiteLLM model. It reads a task, runs one bash command at a time, observes the output, and loops until it submits. The model is routed through LiteLLM, so the same code works with Anthropic Claude, OpenAI, or Google AI Studio (Gemini) — just change MODEL in .env.

Use a capable model (e.g. claude-opus-4-8, gpt-4o). The agent protocol — reply with one mswea_bash_command fence, then submit — is unreliable with small models, which tend to loop or mis-format.

Configure

cd samples/mini-swe-agent_1
cp .env.sample .env
# edit .env: set MODEL and the matching provider key

MODEL picks the provider:

Provider	`MODEL` example	Key in `.env`
Anthropic Claude	`claude-opus-4-8`	`ANTHROPIC_API_KEY`
OpenAI	`gpt-4o`	`OPENAI_API_KEY`
Google AI Studio	`gemini/gemini-2.5-flash`	`GEMINI_API_KEY`
Ollama (local)	`ollama_chat/qwen3.5:9b`	`OLLAMA_API_BASE`

.env is gitignored — only .env.sample is committed.

Ollama (local models): first pull the model on the host — ollama pull qwen3.5:9b (or ollama run qwen3.5:9b). Then set MODEL=ollama_chat/qwen3.5:9b and point OLLAMA_API_BASE at the server — no API key needed. In a devcontainer with DooD the container reaches the host's Ollama at http://host.docker.internal:11434; running locally use http://localhost:11434.

Run with Docker

cd samples/mini-swe-agent_1
docker build -t aas-mini-swe-agent .
docker run --rm --env-file .env aas-mini-swe-agent \
  "Print the result of 2 + 2 using a single shell command, then submit."

Run with Docker (in a devcontainer with DooD)

In a dev container that talks to the host Docker daemon (Docker-outside-of-Docker), the foreground docker run above often prints nothing and exits 0 — but the run itself succeeds. The agent runs to completion and Docker captures all of its output; only the live attached stream drops it over the VM boundary. You can confirm this: docker logs on the same container shows the full output, the container exits 0, and it is not an OOM. Run detached and follow the logs instead:

cd samples/mini-swe-agent_1
docker build -t aas-mini-swe-agent .
docker logs -f "$(docker run -d --env-file .env aas-mini-swe-agent \
  "Print the result of 2 + 2 using a single shell command, then submit.")"

Run locally

cd samples/mini-swe-agent_1
pip install -r requirements.txt
python app.py "Print the result of 2 + 2 using a single shell command, then submit."

python-dotenv loads .env automatically. Get keys from Anthropic, OpenAI, or Google AI Studio.

Example run

Output varies by model and run — LLMs are non-deterministic, so the exact wording (and an agent's steps) differ each time. Below is one run with claude-opus-4-8.

--- assistant ---
THOUGHT: The task simply asks to print the result of 2 + 2 using a single shell command. Let me do that.

```mswea_bash_command
echo $((2 + 2))
```

--- user ---
<returncode>0</returncode>
<output>
4
</output>

--- assistant ---
THOUGHT: The command printed 4 as expected. Now I'll submit.

```mswea_bash_command
echo COMPLETE_TASK_AND_SUBMIT_FINAL_OUTPUT
```

=== Submitted ===

Files

.env.sample

# Copy this file to `.env` and fill in the key for the provider you want.
#   cp .env.sample .env
#
# One codebase, many providers — mini-SWE-agent routes via LiteLLM based on MODEL.
# Use a capable model: the agent protocol is unreliable with small models.

# Pick the model. Examples:
#   claude-opus-4-8              Anthropic Claude   -> needs ANTHROPIC_API_KEY
#   gpt-4o                       OpenAI             -> needs OPENAI_API_KEY
#   gemini/gemini-2.5-flash      Google AI Studio   -> needs GEMINI_API_KEY
#   ollama_chat/qwen3.5:9b       Ollama (local)     -> needs OLLAMA_API_BASE, no key
MODEL=claude-opus-4-8

# Set only the key for the provider you chose; leave the rest blank.
ANTHROPIC_API_KEY=
OPENAI_API_KEY=
GEMINI_API_KEY=

# Ollama only — where the Ollama server runs (pull the model first, e.g.
# `ollama pull qwen3.5:9b`). Other providers ignore this line.
#   Local, no Docker:           http://localhost:11434
#   Docker / DooD on the host:  http://host.docker.internal:11434
OLLAMA_API_BASE=http://host.docker.internal:11434

app.py

"""mini-SWE-agent: a ~100-line coding agent that works with plain shell commands.

The agent reads a task, runs a shell command in its environment, observes the
output, and loops until it submits a result — no special tools, just bash. The
model is routed through LiteLLM, so MODEL in `.env` picks the provider
(claude-opus-4-8 / gpt-4o / gemini/gemini-2.5-flash).

This mirrors mini-SWE-agent's own `hello_world` binding: a DefaultAgent driving
a LocalEnvironment with a text-based LiteLLM model.

Run:
    docker build -t aas-mini-swe-agent .
    docker run --rm --env-file .env aas-mini-swe-agent \
        "Print the result of 2 + 2 using a shell command, then submit."
"""

import os
import sys

import yaml
from dotenv import load_dotenv
from minisweagent import package_dir
from minisweagent.agents.default import DefaultAgent
from minisweagent.environments.local import LocalEnvironment
from minisweagent.models.litellm_textbased_model import LitellmTextbasedModel

# Load .env when running locally; in Docker the keys come from --env-file.
load_dotenv()


DEFAULT_TASK = "Print the result of 2 + 2 using a single shell command, then submit."


def main() -> None:
    task = " ".join(sys.argv[1:]) or DEFAULT_TASK

    # MODEL chooses the provider; LitellmTextbasedModel routes it through LiteLLM.
    model_name = os.environ.get("MODEL", "claude-opus-4-8")

    # Start from mini-SWE-agent's default agent config, but bound the demo.
    agent_config = yaml.safe_load((package_dir / "config" / "default.yaml").read_text())["agent"]
    agent_config["step_limit"] = 15

    # The default config asks the model to reply with a ```mswea_bash_command
    # fence, so pair it with the text-based model (not the tool-calling one).
    agent = DefaultAgent(
        LitellmTextbasedModel(model_name=model_name),
        LocalEnvironment(),
        **agent_config,
    )

    result = agent.run(task)

    # Show the loop unfold: skip the system + instructions (messages 0-1) and
    # print each step's thought/command and the observation it produced.
    for msg in agent.messages[2:]:
        content = msg.get("content", "")
        if isinstance(content, list):  # multimodal parts -> join the text
            content = " ".join(p.get("text", "") for p in content if isinstance(p, dict))
        if content.strip():
            print(f"\n--- {msg.get('role')} ---\n{content.strip()}")

    print(f"\n=== {result.get('exit_status', 'unknown')} ===")
    print(result.get("submission", ""))


if __name__ == "__main__":
    main()

Dockerfile

# Minimal image for the mini-SWE-agent sample.
FROM python:3.13-slim

# Stream stdout/stderr unbuffered so the agent's steps appear live.
ENV PYTHONUNBUFFERED=1

# Some providers (e.g. Gemini) have no price registered in LiteLLM; without this
# mini-SWE-agent's cost tracking would raise instead of running.
ENV MSWEA_COST_TRACKING=ignore_errors

# Silence the package's import-time banner (version + v2 migration notice) so the
# agent's output starts clean. It is just an informational notice, not a warning.
ENV MSWEA_SILENT_STARTUP=1

WORKDIR /app

COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY app.py .

# Provide your config at run time (.env is NOT baked into the image):
#   docker run --rm --env-file .env aas-mini-swe-agent "<task>"
ENTRYPOINT ["python", "app.py"]

Related tools

Overview

When to use it

Pricing

When to use

How it flows

When to use

How it flows

Configure

Run with Docker

Run with Docker (in a devcontainer with DooD)

Run locally

Example run