Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/swe-agent/mini-swe-agent/llms.txt

Use this file to discover all available pages before exploring further.

This page collects the most common questions about mini-swe-agent, organised into three sections. General covers system requirements and when to choose mini over swe-agent. Models covers supported models and API key configuration. Minutia goes deeper on specific design decisions — in particular, why mini deliberately avoids keeping a running shell session.

​
General

mini-SWE-agent should work on any system that has a bash shell or uses a container runtime (e.g. Docker, Singularity, Apptainer) to emulate one.
Use mini-swe-agent if:
  • You want a quick command-line tool that works locally
  • You want an agent with a very simple control flow
  • You want faster, simpler, and more stable sandboxing and benchmark evaluations
  • You are doing fine-tuning or reinforcement learning and don’t want to overfit to a specific agent scaffold
Use swe-agent if:
  • You need specific tools or want to experiment with different tools
  • You want to experiment with different history processors
  • You want powerful YAML configuration without touching code
Both provide:
  • Excellent performance on SWE-Bench
  • A trajectory browser
mini is simpler because it:
  • Has no tools other than bash — it doesn’t even use the tool-calling interface of the LM by default. This means you don’t need to install anything in the environment you’re running in; bash is all you need.
  • Has a completely linear history — every step simply appends to the message list and nothing else.
  • Executes actions with subprocess.run — every action is completely independent (as opposed to keeping a stateful shell session running). This avoids a large class of reliability problems.
The following assumes the default setup. As reflected in high SWE-bench scores, none of these limitations are a problem in practice.
  • No tools other than bash
  • Actions are parsed from fenced code blocks with the mswea_bash_command language tag (or via the native tool-calling API)
  • Actions are executed as independent subprocess.run calls, meaning the agent cannot change directories or export environment variables that persist across actions — however, environment variables can be set per-action, and prefixing cd /path/to/project && to each command works fine
If you need more flexibility with any of these, consider using SWE-agent instead.
Global configuration is stored in the .env file in the config directory. The exact location is printed when you run mini --help.The .env file is a simple key-value file read by the dotenv library. You can edit it directly, or use the mini-extra config set command to update individual values.

​
Models

mini-SWE-agent supports all models supported by litellm or OpenRouter. The models/ directory can be extended with additional model classes if litellm does not cover a specific provider.
You can set the API key as an environment variable (not persistent across sessions unless added to ~/.bashrc or similar):
export OPENAI_API_KEY=sk-test123
To save it permanently in the config file:
mini-extra config set OPENAI_API_KEY sk-test123
Alternatively, edit the .env file in the config directory directly (the path is shown by mini --help).
The default model is read from the MSWEA_MODEL_NAME environment variable / config key. To change it permanently:
mini-extra config set MSWEA_MODEL_NAME anthropic/claude-sonnet-4-5-20250929
You can also set it temporarily as an environment variable, or override it per-run with -c model.model_name=... on the CLI.

​
Minutia

Most agents kept a persistent shell session and pasted each action into it. This approach introduces several hard-to-solve reliability problems:
  1. Detecting command completion is non-trivial. You are essentially watching output from a live shell and guessing when it has finished. Heuristics based on PID watching or waiting for the prompt to reappear are all fragile.
  2. A bad command can kill the shell session. Once the session dies, there is no clean recovery path.
  3. Interrupting a running command can corrupt the shell state. This interferes with every subsequent command’s output.
mini takes a different approach: there is no running shell session. Every action is an independent subprocess.run (or docker exec / equivalent) call. The process runs, terminates, and returns its output — cleanly, every time.The trade-off is that directory changes and exported environment variables do not persist between actions. In practice this is not a problem: you can prefix cd /path/to/project or export FOO=bar to any action that needs it (and models like Claude do this automatically).

Build docs developers (and LLMs) love

Get started for freeTalk to us