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.

YAML configuration files give you precise control over how mini-swe-agent behaves. Rather than passing many flags on every invocation, you write a config file once and reuse it. Configs are especially useful when you want to customize prompt templates, set cost limits, change the action parsing format, or target a specific execution environment. The default mini CLI uses a built-in config file called mini.yaml. You can override it — or layer additional settings on top of it — using the -c/--config flag.

​
Passing a config file

# Use a custom config file
mini --config myconfig.yaml

# Layer overrides on top of the default config
mini -c mini.yaml -c model.model_kwargs.temperature=0.5

# Use a config by name (searched in MSWEA_CONFIG_DIR and built-in dirs)
mini -c swebench.yaml

# Set a single key inline
mini -c agent.cost_limit=2.0
You can also set a default config path with the environment variable: 
export MSWEA_MINI_CONFIG_PATH=/path/to/your/config.yaml
Multiple -c arguments are merged recursively, with later values taking precedence.

​
Top-level config keys

A config file uses four top-level keys: 
agent:      # Prompt templates, limits, output path
model:      # Model name, class, action parsing
environment: # Where commands run (local, docker, etc.)
run:        # Task description

​
Agent configuration

The agent section controls the agent’s behavior, prompts, and resource limits.
FieldTypeDescription
system_templatestringJinja2 template for the system message sent to the model.
instance_templatestringJinja2 template for the first user message (the task).
format_error_templatestringTemplate sent back to the model when action parsing fails.
step_limitintegerMaximum number of steps before the agent stops.
cost_limitfloatMaximum cost in dollars for a single run (0 = no limit).
wall_time_limit_secondsintegerMaximum wall-clock time in seconds for a run.
output_pathstringPath to write the trajectory JSON file.
modestringStarting mode: confirm, yolo, or human.
Example: 
agent:
  step_limit: 30
  cost_limit: 1.50
  output_path: ./runs/my-run.traj.json

​
Jinja2 templating

Prompt templates use Jinja2 syntax. Include variables with double curly braces: 
Your task: {{task}}
You have at most {{step_limit}} steps and a budget of ${{cost_limit}}.
The following variables are available in all built-in agent templates:
VariableSource
taskThe task string passed to the agent at runtime
step_limitFrom agent config
cost_limitFrom agent config
outputOutput of the last action execution (has .output and .returncode)
Agent config fieldsAny field set under agent: in the config
Environment config fieldsAny field set under environment: in the config
Environment variablesAvailable in LocalEnvironment only
You can use full Jinja2 logic in templates. For example, to truncate long command output: 
<returncode>{{output.returncode}}</returncode>
{% if output.output | length < 10000 -%}
<output>
{{ output.output -}}
</output>
{%- else -%}
<warning>Output too long. Try a more selective command.</warning>
<output_head>{{ output.output[:5000] }}</output_head>
<output_tail>{{ output.output[-5000:] }}</output_tail>
{%- endif -%}

​
Action parsing

By default, mini-swe-agent parses actions from fenced code blocks tagged mswea_bash_command: 
```mswea_bash_command
ls -la
```
You can change this by setting action_regex under model: and updating your prompt templates to match. The regex must capture the command in its first group.
This config uses <action> tags instead of markdown code blocks. All templates must be updated to match so the model wraps commands consistently.
model:
  action_regex: <action>(.*?)</action>

agent:
  system_template: |
    You are a helpful assistant. Wrap every bash command in <action> tags.

    Example:
    <action>ls -la</action>

  instance_template: |
    Task: {{task}}

    Remember to wrap commands in <action> tags.

  format_error_template: |
    Your last response did not contain a valid <action>command</action> block.
    Please try again and wrap your command in <action> tags.
If you set a custom action_regex, you must use that same format consistently across all templates (system_template, instance_template, format_error_template). Mixing formats will cause parsing failures.
When writing action_regex in YAML, keep the regex on a single line and do not use quotation marks. You do not need to escape characters. For example:
model:
  action_regex: <bash_code>(.*?)</bash_code>

​
Global configuration (environment variables)

Global settings apply across all runs and can be set as environment variables or in the .env file in your config directory. Environment variables take precedence over .env file values.
VariableDescription
MSWEA_MODEL_NAMEDefault model name (e.g., anthropic/claude-sonnet-4-5-20250929)
MSWEA_GLOBAL_COST_LIMITGlobal cost cap in dollars across all runs (0 = no limit)
MSWEA_GLOBAL_CALL_LIMITGlobal limit on total model API calls (0 = no limit)
MSWEA_CONFIG_DIRAdditional directory to search for config files by name
MSWEA_MINI_CONFIG_PATHDefault config file path for the mini CLI
MSWEA_COST_TRACKINGSet to ignore_errors to suppress cost tracking errors (e.g., for free models)
Use mini-extra config to manage these settings interactively: 
# Interactive setup wizard
mini-extra config setup

# Set a specific key
mini-extra config set MSWEA_MODEL_NAME anthropic/claude-sonnet-4-5-20250929

# Open the .env file in your editor
mini-extra config edit
For model-specific configuration (model class, temperature, reasoning strength), see Models.

Build docs developers (and LLMs) love

Get started for freeTalk to us