mini-swe-agent

mini-SWE-agent is a minimal AI software engineering agent designed for simplicity and performance. Key features include:

• Minimalist Design: Approximately 100 lines of core Python code.
• Bash-Centric: The agent uses only bash as a tool, avoiding complex tool-calling interfaces and making it compatible with any LLM.
• Stateless Actions: Actions are executed via subprocess.run, making each step independent and easy to sandbox (e.g., using Docker or Podman).
• Linear History: The agent maintains a simple, linear message history, which is ideal for debugging and fine-tuning.
• High Performance: Scores >74% on the SWE-bench verified benchmark.
• Flexible Deployment: Supports local environments, Docker/Podman, Singularity/Apptainer, Bublewrap, and Contree.

mini-swe-agent supports several environment types for executing code, depending on your isolation and infrastructure requirements:

• local.py: Executes code directly on the host machine using subprocess.run. Use this for simple tasks where host isolation is not required.
• docker.py: Executes code within a Docker or Podman container. This provides a standard level of containerized isolation.
• singularity.py: Executes code within a Singularity or Apptainer container. This is often used in HPC (High-Performance Computing) environments.

For specialized execution needs, mini-swe-agent provides extra environment implementations:

• extra/swerex_docker.py: Executes environments using Docker via swerex.
• extra/swerex_modal.py: Executes environments using Modal via swerex.
• extra/bubblewrap.py: Executes environments using bubblewrap.

Choose mini-swe-agent if you need a quick, local command-line tool with simple control flow, faster/simpler sandboxing, and a minimal toolset (bash only). It is ideal for Fine-Tuning (FT) or Reinforcement Learning (RL) to avoid overfitting to specific agent scaffolds.

Choose swe-agent if you require advanced tools, custom history processors, or complex YAML-based configurations without modifying code.

Both provide excellent performance on SWE-Bench and include a trajectory browser.

Global configuration is stored in a .env file within the config directory. To find the exact path of this directory on your system, run the following command:

mini --help

The .env file is a standard key-value file compatible with the dotenv library.

You can set API keys for supported models (via litellm or OpenRouter) using one of three methods:

1. Temporary Environment Variable: Set it in your current shell session.
2. Permanent Config via CLI: Use the mini-extra config set command.
3. Manual Edit: Directly edit the .env file in the config directory (location found via mini --help).

# Temporary
export OPENAI_API_KEY=sk-test123

# Permanent
mini-extra config set OPENAI_API_KEY sk-test123

You can set API keys using one of the following methods:

1. Setup Script (Recommended): Run mini-extra config setup.
2. CLI Command: Use mini-extra config set <KEY_NAME> <value> to save a key to the global config file.
3. Environment Variables: Export the key directly in your shell (e.g., export ANTHROPIC_API_KEY=<your-api-key>).

Note: Portkey models specifically require the PORTKEY_API_KEY environment variable. Most other models use keys supported by litellm (e.g., OPENAI_API_KEY, ANTHROPIC_API_KEY, GEMINI_API_KEY, etc.).

mini-extra config set ANTHROPIC_API_KEY <your-api-key>
# OR
export ANTHROPIC_API_KEY=<your-api-key>

Models must be configured during the first run of the mini CLI. If you skip the setup wizard, you can trigger the configuration setup manually using mini-extra config setup.

When specifying models, always include the provider in the name (e.g., anthropic/claude-...).