Headless and CI - MiniMax Agent 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

mcode exec "Run the tests and fix the failures"

Set a workspace and machine-readable output:

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

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:

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

mcode exec "Check the current changes for type errors"

Text from stdin

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

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": "..." }:

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:

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:

{
  "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:

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:

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

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

​Minimal invocation

​Choose task instructions

​Set reasoning effort for one run

​Input

​Positional prompt

​Text from stdin

​JSON from stdin

​Attachments

​Options

​Output formats

​text

​json

​stream-json

​Structured output

​Sessions and recovery

​Timeouts, limits, and cancellation

​Exit codes