> ## 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.

<div className="code-docs">
  `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 |
</div>