Quick start

v1 Documentation

You're currently viewing the v1 docs. For the new version, see github.com/swe-agent/mini-swe-agent and mini-swe-agent.com.

Installation Options

pipuv (isolated)pipx (isolated)From source/dev

Use pip to install mini v1 in your current environment:

pip install 'mini-swe-agent<2'

And try our command line interface

mini  # simple UI
mini -v  # visual UI
mini-extra  # extra utilities

Use uv/uvx (installation) to directly run the mini v1 CLI. Use this if you're only interested in the CLI but don't need python bindings (mini v1 will be installed in an anonymous virtual environment).

Quickly install + run:

uvx 'mini-swe-agent<2'  # simple UI
uvx 'mini-swe-agent<2' -v  # visual UI
uvx --from 'mini-swe-agent<2' mini-extra  # extra utilities

Permanently install

uv tool install 'mini-swe-agent<2'
# then
mini  # simple UI
mini -v  # visual UI
mini-extra  # extra utilities

Use pipx (installation) to directly run the mini CLI. Use this if you're only interested in the CLI but don't need python bindings (mini v1 will be installed in an anonymous virtual environment).

Quick install + run:

# Simple UI
pipx run 'mini-swe-agent<2'
# Textual UI
pipx run 'mini-swe-agent<2' -v
# Extra utilities
pipx run --spec 'mini-swe-agent<2' mini-extra

or for a persistent installation (recommended):

pipx install 'mini-swe-agent<2'
# then
mini  # simple UI
mini -v  # visual UI
mini-extra  # extra utilities

If the invocation doesn't immediately work, you might need to run pipx ensurepath.

For development or if you want to customize the agent based on the v1 codebase (of course, starting with the current main branch would be more recommended):

git clone https://github.com/SWE-agent/mini-swe-agent.git -b v1
cd mini-swe-agent
pip install -e .

Then run:

mini  # simple UI
mini -v  # visual UI
mini-extra  # extra utilities

Or pick a run script:

python src/minisweagent/run/hello_world.py

If you are planning to contribute, please also install the dev dependencies and pre-commit hooks:

pip install -e '.[dev]'
pip install pre-commit && pre-commit install

To check your installation, you can run pytest -n auto in the root folder. This should run all tests in parallel (should take ~3min to run).

Note that there are still some extra dependencies that are not installed by default (basically anything that is in an .../extra/... folder). If you truly want to get the maximal package, you can run pip install -e '.[full]'

Changelog

Please see the github release notes for recent changes.

Example Prompts

Try mini-SWE-agent with these example prompts:

Implement a Sudoku solver in python in the sudoku folder. Make sure the codebase is modular and well tested with pytest.
Please run pytest on the current project, discover failing unittests and help me fix them. Always make sure to test the final solution.
Help me document & type my codebase by adding short docstrings and type hints.

Models

Models should be set up the first time you run mini

If you missed the setup wizard, just run mini-extra config setup
For more information, please check the model setup quickstart.
If you want to use local models, please check this guide.

Tip: Please always include the provider in the model name, e.g., anthropic/claude-....

Which model to use?

We recommend using anthropic/claude-sonnet-4-5-20250929 for most tasks. For openai models, we recommend using openai/gpt-5 or openai/gpt-5-mini. You can check scores of different models at our SWE-bench (bash-only) leaderboard.

Our projects