> ## Documentation Index
> Fetch the complete documentation index at: https://agent-compass.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# mini-SWE-agent

The `mini_swe_agent` harness runs [mini-SWE-agent](https://mini-swe-agent.com) for [SWE-bench](/en/user_guide/modules/benchmarks/swebench_verified)-style repository-repair tasks.

AgentCompass builds a mini-SWE-agent configuration from the model CLI flags and harness parameters, lets the agent edit and test the repository through the selected environment, then collects the requested patch and converts the native trajectory to `RunResult`. Both `openai-chat` and `openai-responses` model protocols are supported.

## How it works

1. **Prepare mini-SWE-agent.** `install_strategy=install_if_missing` imports or locates mini-SWE-agent first and runs `install_command` only when it is absent. `preinstalled` fails immediately when the package or executable is unavailable.
2. **Run the repair loop.** The agent queries the model, executes shell tool calls in the prepared repository, and continues until it submits, reaches a limit, or errors.
3. **Collect the patch and trajectory.** Requested output files take precedence as `final_answer`; otherwise the native submission or command output is used. The native trajectory is also retained as an artifact.

### Local and remote launch modes

`launch_mode` controls where the mini-SWE-agent Python loop runs, not where repository commands run:

| Mode              | Agent process                                                                                                                                 | Shell commands                                                                                                       |
| ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
| `local` (default) | Runs in the AgentCompass controller process by importing the `minisweagent` package. Installation, if needed, also happens on the controller. | Forwarded through the selected `EnvironmentSession`, so Docker/Modal/Daytona commands still run inside that sandbox. |
| `remote`          | Runs the `mini` CLI inside the selected environment. Installation, if needed, happens in that environment.                                    | Executed directly in the same environment and workspace.                                                             |

Use `local` for the normal AgentCompass integration and consistent live trajectory conversion. Use `remote` only when the target image already contains mini-SWE-agent or can install and run it there.

The harness currently selects mini-SWE-agent's [`swebench.yaml` base config](https://github.com/SWE-agent/mini-swe-agent/blob/main/src/minisweagent/config/benchmarks/swebench.yaml) for `swebench_verified`, `swebench_pro`, and `swebench_multilingual`. Other benchmarks use [`mini.yaml`](https://github.com/SWE-agent/mini-swe-agent/blob/main/src/minisweagent/config/mini.yaml). AgentCompass then overlays the parameters documented below.

### Timeout and limit layers

Both JSON flags contain a field named `timeout`, but with different meanings: `--harness-params.timeout` limits the whole agent run, while `--model-params.timeout` limits one model request.

| Layer                | Configuration              | Default                                              | Scope                                                                                                                                                     |
| -------------------- | -------------------------- | ---------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| LLM request          | `--model-params.timeout`   | unset by AgentCompass                                | One LiteLLM Chat Completions or Responses request. When omitted, the LiteLLM/provider default applies, typically `600` seconds.                           |
| Shell command        | `command_timeout`          | `2400` seconds                                       | One bash tool call executed through the selected environment. `null` disables this per-command limit.                                                     |
| Agent steps          | `step_limit`               | `250` steps                                          | Maximum model/tool loop steps; this is a count limit, not a duration.                                                                                     |
| Agent cost           | `cost_limit`               | `3.0`                                                | Maximum cumulative cost reported by mini-SWE-agent/LiteLLM. With `cost_tracking=ignore_errors`, unknown provider pricing is not treated as a fatal error. |
| Whole inference task | `--harness-params.timeout` | `null`                                               | Wall-clock limit for the complete mini-SWE-agent run. Because the default is unlimited, set it explicitly for bounded benchmark runs.                     |
| SWE evaluation       | benchmark `eval_timeout`   | Verified / Multilingual: `1800`; Pro: `3600` seconds | Fresh benchmark evaluation after patch collection. It does not control inference, model requests, or shell commands.                                      |

The earliest applicable limit wins. For example, with harness `timeout=7200` and model `timeout=9000`, the whole-task timeout can cancel the run before that model request reaches its own limit.

## Parameters

Pass a JSON object via `--harness-params '{...}'`, or use `harness.params` in a YAML file given to `--config`; the CLI wins on shared keys. See the [Harnesses overview](/en/user_guide/modules/harnesses/overview) for merge precedence.

### Parameter reference

<div style={{overflowX:'auto'}}>
  <table style={{minWidth:'1160px', width:'100%'}}>
    <colgroup>
      <col width="23%" />

      <col width="14%" />

      <col width="19%" />

      <col width="14%" />

      <col width="30%" />
    </colgroup>

    <thead>
      <tr><th style={{whiteSpace:'nowrap'}}>Parameter</th><th style={{whiteSpace:'nowrap'}}>Type</th><th style={{whiteSpace:'nowrap'}}>Default</th><th>Choices / values</th><th>Description</th></tr>
    </thead>

    <tbody>
      <tr><td style={{whiteSpace:'nowrap'}}><code>binary</code></td><td>string</td><td><code>mini</code></td><td>executable name or path</td><td>CLI used by <code>remote</code> mode. Local mode imports the Python package.</td></tr>
      <tr><td style={{whiteSpace:'nowrap'}}><code>launch\_mode</code></td><td>string</td><td><code>local</code></td><td><code>local</code> / <code>remote</code></td><td>Where the mini-SWE-agent loop runs; repository commands still use the selected environment.</td></tr>
      <tr><td style={{whiteSpace:'nowrap'}}><code>install\_strategy</code></td><td>string</td><td><code>install\_if\_missing</code></td><td><code>preinstalled</code> / <code>install\_if\_missing</code></td><td>Whether to require an existing installation or install only when missing.</td></tr>
      <tr><td style={{whiteSpace:'nowrap'}}><code>install\_command</code></td><td>string</td><td><code>pip install mini-swe-agent==1.23.0</code></td><td>shell command</td><td>Command used by <code>install\_if\_missing</code>. It runs on the controller in local mode and inside the environment in remote mode. The default version is pinned to `1.23.0`.</td></tr>
      <tr><td style={{whiteSpace:'nowrap'}}><code>step\_limit</code></td><td>int</td><td><code>250</code></td><td>integer ≥ 1</td><td>Maximum agent steps per task.</td></tr>
      <tr><td style={{whiteSpace:'nowrap'}}><code>cost\_limit</code></td><td>float</td><td><code>3.0</code></td><td>number > 0</td><td>Maximum cumulative cost reported by mini-SWE-agent/LiteLLM.</td></tr>
      <tr><td style={{whiteSpace:'nowrap'}}><code>cost\_tracking</code></td><td>string</td><td><code>ignore\_errors</code></td><td><code>default</code> / <code>ignore\_errors</code></td><td>Whether missing or unknown provider cost metadata aborts the run.</td></tr>
      <tr><td style={{whiteSpace:'nowrap'}}><code>env</code></td><td>dict</td><td><code>\{}</code></td><td>string-to-string mapping</td><td>Additional environment variables for repository commands.</td></tr>
      <tr><td style={{whiteSpace:'nowrap'}}><code>timeout</code></td><td>int / null</td><td><code>null</code></td><td>integer ≥ 1 or <code>null</code></td><td>Whole-task wall-clock timeout, in seconds. <code>null</code> disables it.</td></tr>
      <tr><td style={{whiteSpace:'nowrap'}}><code>command\_timeout</code></td><td>int / null</td><td><code>2400</code></td><td>integer ≥ 1 or <code>null</code></td><td>Timeout for one shell tool call, in seconds. <code>null</code> disables it.</td></tr>
    </tbody>
  </table>
</div>

### Model configuration

Model credentials come from `--model-base-url` and `--model-api-key`; request options come from `--model-params`. For an OpenAI-compatible endpoint, the base URL should normally end in `/v1`.

AgentCompass writes `--model-params` into mini-SWE-agent's [`model.model_kwargs`](https://mini-swe-agent.com/latest/reference/models/litellm/). The `openai-chat` path passes those fields to `litellm.completion`; the `openai-responses` path passes them to `litellm.responses`. The harness adds `drop_params=true` and `parallel_tool_calls=true` unless an explicit model parameter overrides them, and sets `custom_llm_provider=openai` when a custom base URL is supplied.

| Parameter             | AgentCompass default | Scope                                                                                                 |
| --------------------- | -------------------- | ----------------------------------------------------------------------------------------------------- |
| `temperature`         | unset                | Sampling temperature for one model response.                                                          |
| `max_tokens`          | unset                | Chat Completions output-token limit. Use the name expected by the provider.                           |
| `max_output_tokens`   | unset                | Responses API output-token limit.                                                                     |
| `timeout`             | unset                | Timeout for one model request; independent of harness `timeout` and `command_timeout`.                |
| `reasoning_effort`    | unset                | Chat Completions reasoning level for compatible LiteLLM/provider routes.                              |
| `reasoning`           | unset                | Responses API reasoning object, for example `{"effort":"high"}`.                                      |
| `extra_body`          | unset                | Provider-specific OpenAI-compatible request body, including vLLM chat-template options.               |
| `thinking`            | unset                | Provider-specific extended-thinking object, such as Anthropic's budget configuration.                 |
| `drop_params`         | `true`               | Ask LiteLLM to drop unsupported optional parameters. Set `false` when strict rejection is preferable. |
| `parallel_tool_calls` | `true`               | Allow the model to return multiple shell tool calls in one response when supported.                   |

#### Thinking and reasoning

There is no mini-SWE-agent harness parameter named `thinking`; pass the provider-specific form through `--model-params`.

<Tabs>
  <Tab title="Chat Completions">
    For a Chat Completions endpoint that supports reasoning effort:

    ```bash theme={"system"}
    --model-api-protocol openai-chat \
    --model-params '{
      "temperature": 0,
      "max_tokens": 32768,
      "timeout": 3600,
      "reasoning_effort": "high"
    }'
    ```
  </Tab>

  <Tab title="Responses API">
    AgentCompass selects mini-SWE-agent's `litellm_response` model class and passes the `reasoning` object to `litellm.responses`:

    ```bash theme={"system"}
    --model-api-protocol openai-responses \
    --model-params '{
      "max_output_tokens": 32768,
      "timeout": 3600,
      "reasoning": {
        "effort": "high"
      }
    }'
    ```
  </Tab>

  <Tab title="vLLM / Qwen thinking switch">
    For an OpenAI-compatible [vLLM reasoning endpoint](https://docs.vllm.ai/en/latest/features/reasoning_outputs/), forward the chat-template switch in `extra_body`. The server must have matching reasoning and tool-call parsers enabled.

    ```bash theme={"system"}
    --model-api-protocol openai-chat \
    --model-params '{
      "max_tokens": 32768,
      "timeout": 3600,
      "extra_body": {
        "chat_template_kwargs": {
          "enable_thinking": true
        }
      }
    }'
    ```
  </Tab>
</Tabs>

Reasoning fields are provider-specific; do not mix the Chat Completions, Responses, and chat-template forms unless the server documents that combination. Thinking tokens consume the output/context budget.

## Run examples

<Tabs>
  <Tab title="Default configuration">
    Use the default local launch mode: the controller runs the agent loop, while shell commands execute in the task-specific Docker environment.

    ```bash theme={"system"}
    agentcompass run \
      swebench_verified \
      mini_swe_agent \
      "$MODEL_NAME" \
      --env docker \
      --benchmark-params '{"sample_ids":["astropy__astropy-12907"]}' \
      --model-base-url "$MODEL_BASE_URL" \
      --model-api-key "$MODEL_API_KEY" \
      --model-api-protocol openai-chat
    ```
  </Tab>

  <Tab title="Custom parameters">
    Customize model requests, shell commands, the agent loop, total cost, and the whole-task timeout.

    ```bash theme={"system"}
    agentcompass run \
      swebench_verified \
      mini_swe_agent \
      "$MODEL_NAME" \
      --env docker \
      --benchmark-params '{"sample_ids":["astropy__astropy-12907"]}' \
      --harness-params '{
        "step_limit": 300,
        "cost_limit": 5.0,
        "command_timeout": 1800,
        "timeout": 7200
      }' \
      --model-params '{
        "temperature": 0,
        "max_tokens": 32768,
        "timeout": 3600,
        "reasoning_effort": "high"
      }' \
      --model-base-url "$MODEL_BASE_URL" \
      --model-api-key "$MODEL_API_KEY" \
      --model-api-protocol openai-chat
    ```
  </Tab>
</Tabs>

To run the `mini` CLI inside the task environment instead, set `launch_mode=remote`; `install_strategy=install_if_missing` installs it there when absent.

## Output

The harness returns one `RunResult` per task:

* `final_answer` — the first requested output file, normally `patch.txt`; otherwise the native submission or stdout;
* `trajectory` — the normalized model/tool trajectory, including an unfinished-command step when a local run times out during tool execution;
* `artifacts.file` — requested files collected from the workspace;
* `artifacts.mini_swe_agent_raw_trajectory` — the native mini-SWE-agent trajectory;
* `metrics` — launch mode, workspace, native config and trajectory paths, exit/stdout/stderr, selected model protocol, output paths, and timeout diagnostics.

A non-zero agent exit, whole-task timeout, or missing requested output file produces `RUN_ERROR`. The benchmark stores the harness result together with evaluation data under `results/<benchmark>/<model>/<run>/details/`; see [Results](/en/user_guide/results).