mini-swe-agent Documentation and Minimal AI Agent Tutorial
by SWE-agent team (Princeton and Stanford)
Read a 100-line coding agent that scores above 74% on SWE-bench Verified, then build your own in about 60 lines of Python.
Overview
mini-swe-agent is an open-source coding agent from the Princeton and Stanford team behind SWE-bench and SWE-agent, and its documentation site doubles as a short course in how coding agents actually work. The agent class is about 100 lines of Python, gives the model no tool other than bash, skips the provider's tool-calling interface, keeps a linear message history and runs every action through subprocess.run, which makes sandboxing simple. The project page reports scores above 74% on SWE-bench Verified. The docs are split into Getting Started (Quick start, Command line usage, Language models, Configuration, Python bindings, FAQ) and an API Reference covering Agents, Models, Environments and Run Scripts. The interactive mini CLI has confirm, yolo and human modes plus step and cost limits, and a YAML config controls Jinja2 prompt templates, the action-parsing regex, the environment (local, Docker or Podman, Singularity/Apptainer, Bubblewrap) and the model, routed through LiteLLM, OpenRouter or Portkey. The companion tutorial at minimal-agent.com, by Kilian Lieret, Carlos Jimenez, John Yang and Ofir Press, builds a first agent in about 50 lines (query the model, parse the action, execute it, add a system prompt) and then makes it robust with exception-based control flow and format-error handling. Version 2.0.0 shipped on February 11, 2026 and 2.4.6 on July 23, 2026 (PyPI, checked November 14, 2026). The code is MIT-licensed, and the GitHub repo had about 9.6k stars on that date.
At a Glance
- Topic
- Agentic
- Level
- Intermediate
- Format
- Documentation
- Cost
- Free
- Duration
- ~1-2 hours for the from-scratch tutorial and quick start, self-paced; longer if you set up batch SWE-bench runs
- Provider
- SWE-agent team (Princeton and Stanford)
- Hands-on
- Yes — code/exercises
- Certificate
- None
What You’ll Learn
- ✓Build a working agent loop that queries a model, parses a bash command and executes it
- ✓Add a system prompt and feed command output back to the model until it signals completion
- ✓Handle malformed model outputs and control flow with custom exceptions and format-error messages
- ✓Set environment variables that stop pagers and interactive tools from hanging an unattended agent
- ✓Run the mini CLI in confirm, yolo or human mode with step and cost limits
- ✓Configure system, instance and observation templates and the action regex in YAML
- ✓Swap execution environments between local, Docker or Podman, Singularity and Bubblewrap sandboxes
- ✓Connect any model through LiteLLM, OpenRouter or Portkey and run batch SWE-bench evaluations
Highlights
- •Written by the SWE-bench and SWE-agent authors, so the benchmark harness and the agent come from the same team
- •The whole agent class is about 100 lines, small enough to read in one sitting and modify safely
- •Reports above 74% on SWE-bench Verified without tool calling, which makes it a useful baseline for comparing models
- •The README lists Meta, NVIDIA, IBM, Nebius and Anyscale among its users; about 9.6k GitHub stars as of November 14, 2026
- •Actively maintained: v2 rewrite released February 2026, with a migration guide and the v1 code kept on a separate branch
Who It’s For
Best For
- ✓AI engineers who want to understand how coding agents work before adopting a heavier framework
- ✓Researchers who need a simple, reproducible agent baseline for SWE-bench style evaluations
- ✓Platform teams deciding how to sandbox agent shell commands with Docker, Podman or Bubblewrap
- ✓Developers building their first agent from scratch in plain Python
Prerequisites
- •Working Python, including functions and basic type hints, plus Python 3.10 or later installed
- •Comfort with the terminal and shell commands
- •An API key for at least one model provider (OpenAI, Anthropic, OpenRouter or similar)
- •Docker or Podman if you want sandboxed or batch SWE-bench runs
FAQ
What is mini-swe-agent Documentation and Minimal AI Agent Tutorial?
mini-swe-agent is the SWE-bench team's minimal coding agent, and its docs plus companion tutorial show developers how a bash-only agent loop works end to end. It suits engineers who want to understand or extend coding agents. Afterwards you can build, configure, sandbox and benchmark a working agent of your own.
Is mini-swe-agent Documentation and Minimal AI Agent Tutorial free?
mini-swe-agent Documentation and Minimal AI Agent Tutorial is free to access.
What level is mini-swe-agent Documentation and Minimal AI Agent Tutorial for?
mini-swe-agent Documentation and Minimal AI Agent Tutorial is aimed at a intermediate audience. Recommended background: Working Python, including functions and basic type hints, plus Python 3.10 or later installed, Comfort with the terminal and shell commands, An API key for at least one model provider (OpenAI, Anthropic, OpenRouter or similar), Docker or Podman if you want sandboxed or batch SWE-bench runs.
How long does mini-swe-agent Documentation and Minimal AI Agent Tutorial take?
Expect roughly ~1-2 hours for the from-scratch tutorial and quick start, self-paced; longer if you set up batch SWE-bench runs. Most learners work through it at their own pace.
What will I learn from mini-swe-agent Documentation and Minimal AI Agent Tutorial?
You'll learn: Build a working agent loop that queries a model, parses a bash command and executes it; Add a system prompt and feed command output back to the model until it signals completion; Handle malformed model outputs and control flow with custom exceptions and format-error messages; Set environment variables that stop pagers and interactive tools from hanging an unattended agent; Run the mini CLI in confirm, yolo or human mode with step and cost limits; Configure system, instance and observation templates and the action regex in YAML; Swap execution environments between local, Docker or Podman, Singularity and Bubblewrap sandboxes; Connect any model through LiteLLM, OpenRouter or Portkey and run batch SWE-bench evaluations.
Topics
Sources
This page was written from 7 sources, 4 on domains other than mini-swe-agent.com.