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

# Headless and CI

> Use mcode exec from Shell, CI, batch jobs, and evaluations with structured output and stable exit codes.

`mcode exec` runs one task without starting the TUI. It is designed for automation, batch processing, and reproducible evaluations. Before running, sign in or configure a working API-key provider.

## Minimal invocation

```bash theme={null}
mcode exec "Run the tests and fix the failures"
```

Set a workspace and machine-readable output:

```bash theme={null}
mcode exec \
  --cwd ./repo \
  --output-format json \
  "Analyze the failure log, fix the issue, and run the relevant tests"
```

## Choose task instructions

Starting with 0.4.7, regular `mcode exec` tasks can select system instructions with `--prompt-mode`:

| Mode | Purpose |
| - | - |
| `tui` | Terminal task instructions; the default |
| `coding` | Coding task instructions |
| `work` | General work instructions |

```bash theme={null}
mcode exec --prompt-mode coding "Run the tests and fix the failures"
mcode exec --prompt-mode work "Organize the project documentation in the current directory"
```

Each mode uses a complete system template bundled with the installation. Tools and permissions still follow the current TUI configuration. This option applies to regular `exec` tasks.

When resuming with `--session` or `--continue`, the selected mode must match the saved session mode. Pass the same `--prompt-mode` again for a session using a non-default mode. Start a new session if an older session has no saved mode information.

## Set reasoning effort for one run

Starting with 0.4.9, `mcode exec` and `mcode exec review` accept `--effort` as a run-only override:

```bash theme={null}
mcode exec --effort high "Analyze the migration plan"
mcode exec review --effort high --cwd ./repo
```

Use `--effort` on its own or together with `--model`. The level must be supported by the selected model. Unsupported levels and models without effort support fail with a non-zero exit code before the task starts.

The override is not saved to the session. Resuming later with `--session` or `--continue` and no `--effort` uses the session's original level. `#variant` is part of a model identity: `--model provider/model#high` does not replace `--effort high`.

## Input

### Positional prompt

```bash theme={null}
mcode exec "Check the current changes for type errors"
```

### Text from stdin

Read stdin only when explicitly requested with `--input -`:

```bash theme={null}
cat task.txt | mcode exec --input -
```

Do not combine `--input -` with a positional prompt.

### JSON from stdin

`--input-format json` accepts a JSON string or an object such as `{ "prompt": "..." }`:

```bash theme={null}
printf '%s\n' '{"prompt":"Analyze the build failure"}' \
  | mcode exec --input - --input-format json --output-format json
```

### Attachments

Use `--file` for code, logs, images, videos, and other supported files. Paths resolve relative to `--cwd`:

```bash theme={null}
mcode exec \
  --cwd ./repo \
  --file logs/build.log \
  --file screenshots/failure.png \
  "Use the attachments to locate the build failure"
```

A run accepts up to 10 files and 100 MB total. A file-only invocation is valid when at least one `--file` is provided.

## Options

| Option | Purpose |
| - | - |
| `--input -` | Explicitly read stdin; only `-` is supported |
| `--input-format <format>` | `text` or `json`, default `text` |
| `--cwd <path>` | Workspace directory, default current directory |
| `--file <path>` | Repeatable attachment option |
| `--model <provider/model[#variant]>` | Override the model for this run |
| `--effort <level>` | Override reasoning effort for this run; must be supported by the model |
| `--prompt-mode <mode>` | `tui`, `coding`, or `work`; default `tui`; selects system instructions for regular `exec` |
| `--session <id>` | Run in an existing active session |
| `--continue` | Continue the latest active session in `--cwd` |
| `--config <path>` | Use an explicit Runtime configuration file |
| `--permission <policy>` | `smart`, `full`, or `off`, default `smart` |
| `--timeout <duration>` | Timeout such as `30s` or `2m`; supports `ms`, `s`, `m`, `h` |
| `--max-steps <count>` | Limit Assistant steps |
| `--output-format <format>` | `text`, `json`, or `stream-json`, default `text` |
| `--output-schema <schema>` | Inline JSON Schema or Schema file path |
| `-o, --output-last-message <path>` | Write the final Agent message after success |

`--session` and `--continue` cannot be combined. Headless rejects `--permission ask` because it has no interactive host; use the TUI or ACP when a human must approve an action.

## Output formats

Task results go to stdout and diagnostics go to stderr, so stdout can be passed safely to `jq`, CI artifacts, or another process.

### text

Prints the final answer for humans or simple Shell pipelines.

### json

Prints one stable `ExecResult` JSON document:

```json theme={null}
{
  "schemaVersion": 1,
  "type": "exec.result",
  "runId": "run_...",
  "sessionId": "session_...",
  "turnId": "turn_...",
  "status": "succeeded",
  "output": "Final answer",
  "model": {
    "providerId": "minimax_oauth",
    "modelId": "model-id"
  },
  "usage": {
    "totalTokens": 1234,
    "inputTokens": 800,
    "outputTokens": 434
  },
  "durationMs": 4567
}
```

`status` can be `succeeded`, `failed`, `timeout`, `cancelled`, or `limit_exceeded`. The `error`, `model`, and `usage` fields are optional; check `status` first.

### stream-json

Prints newline-delimited, versioned events for live progress. Events include `schemaVersion`, `sequence`, `timestampMs`, `runId`, `sessionId`, and `turnId`. Common types are:

* `exec.started` and `exec.completed`;
* `session.started` and `session.resumed`;
* `turn.started`, `turn.completed`, and `turn.failed`;
* `item.started`, `item.updated`, and `item.completed`.

Process events by `sequence` and preserve forward compatibility for unknown event types.

## Structured output

`--output-schema` accepts an inline JSON object or a Schema file. The final answer must be JSON matching the Schema:

```bash theme={null}
mcode exec \
  --output-format json \
  --output-schema '{"type":"object","required":["summary"],"properties":{"summary":{"type":"string"}}}' \
  "Summarize the current changes"
```

Parsing or validation failures return `status: failed` with error code `STRUCTURED_OUTPUT_INVALID`. `--output-last-message` writes atomically only after a successful run and Runtime shutdown; a write failure is reported as a failure.

## Sessions and recovery

Continue an existing session in a selected workspace:

```bash theme={null}
mcode exec --cwd ./repo --continue "Finish the remaining tests"
mcode exec --session <session-id> "Inspect the previous change"
```

If a session has a pending questionnaire or permission request, Headless does not wait for it. The run returns an interaction error and asks you to use the TUI or ACP first.

## Timeouts, limits, and cancellation

```bash theme={null}
mcode exec --timeout 2m --max-steps 20 "Run the smallest verification"
```

`SIGINT`, `SIGTERM`, and `SIGHUP` cancel the current run. In CI, set a timeout and step limit, and preserve stdout and stderr separately.

## Exit codes

Check both the process exit code and the JSON `status`:

| Exit code | Meaning |
| -: | - |
| `0` | Success |
| `2` | Invocation or input error |
| `3` | Configuration error |
| `4` | Runtime or task failure |
| `6` | Timeout |
| `7` | Runtime limit exceeded |
| `70` | Internal error |
| `130` | Interrupted by Ctrl+C or another cancellation signal |
| `141` | Broken pipe because the downstream pipe closed |