Configuration

Configuring mini

This guide shows how to configure the mini agent.
You should already be familiar with the quickstart guide.
Want more? See the cookbook for subclassing & developing your own agent.

Environment variables and global configuration

Setting up models

This is also covered in the quickstart guide.

All global configuration can be either set as environment variables, or in the .env file (the exact location is printed when you run mini). Environment variables take precedence over variables set in the .env file.

We provide several helper functions to update the global configuration.

For example, to set the default model and API keys, you can run:

mini-extra config setup

or to update specific settings:

mini-extra config set KEY VALUE
# e.g.,
mini-extra config set MSWEA_MODEL_NAME "claude-sonnet-4-20250514"
mini-extra config set MSWEA_MODEL_API_KEY "sk-..."

or to unset a key:

mini-extra config unset KEY
# e.g.,
mini-extra config unset MSWEA_MODEL_API_KEY

You can also edit the .env file directly and we provide a helper function for that:

mini-extra config edit

Models and keys

# Default model name
# (default: not set)
MSWEA_MODEL_NAME="claude-sonnet-4-20250514"

# Default API key
# (default: not set)
MSWEA_MODEL_API_KEY="sk-..."

For Anthropic models, you can also use ANTHROPIC_API_KEYS for advanced parallel execution:

# Multiple Anthropic keys for parallel execution (separated by "::")
ANTHROPIC_API_KEYS="key1::key2::key3"

This allows different threads to use different API keys to avoid prompt caching conflicts when running multiple agents in parallel.

Global cost limits:

# Global limit on number of model calls (0 = no limit)
# (default: 0)
MSWEA_GLOBAL_CALL_LIMIT="100"

# Global cost limit in dollars (0 = no limit)
# (default: 0)
MSWEA_GLOBAL_COST_LIMIT="10.00"

Default config files

# Set a custom directory for agent config files in addition to the builtin ones
# This allows to specify them by names
MSWEA_CONFIG_DIR="/path/to/your/own/config/dir"

# Config path for mini run script
# (default: package_dir / "config" / "mini.yaml")
MSWEA_MINI_CONFIG_PATH="/path/to/your/own/config"

# Config path for GitHub issue script
# (default: package_dir / "config" / "github_issue.yaml")
MSWEA_GITHUB_CONFIG_PATH="/path/to/your/github/config.yaml"

# Custom style path for trajectory inspector
# (default: package_dir / "config" / "mini.tcss")
MSWEA_INSPECTOR_STYLE_PATH="/path/to/your/inspector/style.tcss"

# Custom style path for mini textual interface
# (default: package_dir / "config" / "mini.tcss")
MSWEA_MINI_STYLE_PATH="/path/to/your/mini/style.tcss"

Default run files

# Default run script entry point for the main CLI
# (default: "minisweagent.run.mini")
MSWEA_DEFAULT_RUN="minisweagent.run.mini"

Agent configuration files

Configuration files look like this:

Configuration file

agent:
  system_template: |
    You are a helpful assistant that can interact with a computer.

    Your response must contain exactly ONE bash code block with ONE command (or commands connected with && or ||).
    Include a THOUGHT section before your command where you explain your reasoning process.
    Format your response as shown in <format_example>.

    <format_example>
    Your reasoning and analysis here. Explain why you want to perform the action.

    ```bash
    your_command_here
    ```
    </format_example>

    Failure to follow these rules will cause your response to be rejected.
    To finish, issue the following command: `echo MINI_SWE_AGENT_FINAL_OUTPUT`
    without any other command.
  instance_template: |
    Please solve this issue: {{task}}

    You can execute bash commands and edit files to implement the necessary changes.

    ## Recommended Workflow
    1. Analyze the codebase by finding and reading relevant files.
       If present, you might want to take a look at the following files that set additional guidelines
       for your work: CLAUDE.md, .cursor/rules/<relevant rules>
    2. Create a script to reproduce the issue
    3. Edit the source code to resolve the issue
    4. Verify your fix works by running your script again
    5. Test edge cases to ensure your fix is robust

    ## Important Rules

    1. Every response must contain exactly one action
    2. The action must be enclosed in triple backticks
    3. Directory or environment variable changes are not persistent. Every action is executed in a new subshell.
       However, you can prefix any action with `MY_ENV_VAR=MY_VALUE cd /path/to/working/dir && ...` or write/load environment variables from files
    4. To finish, issue the following command: `echo MINI_SWE_AGENT_FINAL_OUTPUT`.
       Do not combine it with any other command.

    <system_information>
    {{system}} {{release}} {{version}} {{machine}} {{processor}}
    </system_information>

    ## Formatting your response

    Here is an example of a correct response:

    <example_response>
    THOUGHT: I need to understand the structure of the repository first. Let me check what files are in the current directory to get a better understanding of the codebase.

    ```bash
    ls -la
    ```
    </example_response>

    ## Useful command examples

    ### Create a new file:

    ```bash
    cat <<'EOF' > newfile.py
    import numpy as np
    hello = "world"
    print(hello)
    EOF
    ```

    ### Edit files with sed:

    {%- if system == "Darwin" -%}
    <important>
    You are on MacOS. For all the below examples, you need to use `sed -i ''` instead of `sed -i`.
    </important>
    {%- endif -%}

    ```bash
    # Replace all occurrences
    sed -i 's/old_string/new_string/g' filename.py

    # Replace only first occurrence
    sed -i 's/old_string/new_string/' filename.py

    # Replace first occurrence on line 1
    sed -i '1s/old_string/new_string/' filename.py

    # Replace all occurrences in lines 1-10
    sed -i '1,10s/old_string/new_string/g' filename.py
    ```

    ### View file content:

    ```bash
    # View specific lines with numbers
    nl -ba filename.py | sed -n '10,20p'
    ```

    ### Any other command you want to run

    ```bash
    anything
    ```
  action_observation_template: |
    <returncode>{{output.returncode}}</returncode>
    {% if output.output | length < 10000 -%}
    <output>
    {{ output.output -}}
    </output>
    {%- else -%}
    <warning>
    The output of your last command was too long.
    Please try a different command that produces less output.
    If you're looking at a file you can try use head, tail or sed to view a smaller number of lines selectively.
    If you're using grep or find and it produced too much output, you can use a more selective search pattern.
    If you really need to see something from the full command's output, you can redirect output to a file and then search in that file.
    </warning>
    {%- set elided_chars = output.output | length - 10000 -%}
    <output_head>
    {{ output.output[:5000] }}
    </output_head>
    <elided_chars>
    {{ elided_chars }} characters elided
    </elided_chars>
    <output_tail>
    {{ output.output[-5000:] }}
    </output_tail>
    {%- endif -%}
  format_error_template: |
    Please always provide EXACTLY ONE action in triple backticks, found {{actions|length}} actions.
    If you want to end the task, please issue the following command: `echo MINI_SWE_AGENT_FINAL_OUTPUT`
    without any other command.
    Else, please format your response exactly as follows:

    <response_example>
    Here are some thoughts about why you want to perform the action.

    ```bash
    <action>
    ```
    </response_example>
  step_limit: 0.
  cost_limit: 3.
  mode: confirm
environment:
  env:
    PAGER: cat
    MANPAGER: cat
    LESS: -R
    PIP_PROGRESS_BAR: 'off'
    TQDM_DISABLE: '1'
model:
  model_kwargs:
    temperature: 0.0
    drop_params: true

We use Jinja2 to render templates (e.g., the instance template). TL;DR: You include variables with double curly braces, e.g. {{task}}, but you can also do fairly complicated logic like this:

Example: Dealing with long observations

<returncode>{{output.returncode}}</returncode>
{% if output.output | length < 10000 -%}
    <output>
        {{ output.output -}}
    </output>
{%- else -%}
    <warning>
        The output of your last command was too long.
        Please try a different command that produces less output.
        If you're looking at a file you can try use head, tail or sed to view a smaller number of lines selectively.
        If you're using grep or find and it produced too much output, you can use a more selective search pattern.
        If you really need to see something from the full command's output, you can redirect output to a file and then search in that file.
    </warning>

    {%- set elided_chars = output.output | length - 10000 -%}

    <output_head>
        {{ output.output[:5000] }}
    </output_head>

    <elided_chars>
        {{ elided_chars }} characters elided
    </elided_chars>

    <output_tail>
        {{ output.output[-5000:] }}
    </output_tail>
{%- endif -%}

In all builtin agents, you can use the following variables:

Environment variables
Agent config variables
Environment config variables
Explicitly passed variables (observation, task etc.) depending on the template

bug_report Something broken/unclear?

Open an issue on GitHub!

help Open-ended discussions

Join our Slack!

Our projects