Python SDK - MiniMax Code Docs

The Python SDK gives you the same control as the TypeScript SDK from Python code: start Threads, run Turns, stream events, and resume Sessions.Every Turn runs one local mcode exec --output-format=stream-json process and continues the Session with --session. The package is 0.x, so APIs may change between minor versions until 1.0.Related pages: TypeScript SDK, Headless and CI. Package: PyPI minimax-code-sdk.

Requirements

Component	Requirement
Python	`>=3.10`
MiniMax Code CLI (`mcode`)	`>=0.6.3`
Event `schemaVersion`	`1`

The SDK does not install the CLI. Install it separately and sign in, or configure a working API-key provider in the data directory, before the first run.

Installation

pip install minimax-code-sdk        # or: uv add minimax-code-sdk
npm install -g @minimax-ai/code     # the mcode CLI

Import the package as minimax_code.

Quick start

import asyncio
from minimax_code import MCode, ThreadOptions


async def main() -> None:
    client = MCode()
    thread = client.start_thread(ThreadOptions(cwd=".", permission="smart"))

    turn = await thread.run("Summarize this repository in one sentence.")
    print(thread.id, turn.final_response, turn.usage)

    # Same Session, next Turn
    turn = await thread.run("Now list its top-level directories.")
    print(turn.final_response)


asyncio.run(main())

run() returns a Turn only when the status is succeeded. It carries final_response, normalized items, usage, model, session_id, turn_id, duration_ms, and the full CLI result. Every other outcome raises.

Blocking API

If your code is not async, use SyncMCode. It has the same methods without await:

from minimax_code import SyncMCode

with SyncMCode() as client:
    thread = client.start_thread()
    print(thread.run("hello").final_response)
    for event in thread.run_streamed("again"):
        print(event["type"])

SyncMCode runs its own event loop, so it cannot be used where a loop is already running, such as a Jupyter notebook or inside an async def function. There, running a Turn raises a single RuntimeError that points you to the async API. Use MCode with await instead.

CLI resolution

Lookup order:

MCodeOptions(bin=...);
The MCODE_BIN environment variable;
mcode on PATH.

The SDK never starts the CLI through a shell. A missing CLI raises MCodeNotFoundError. Before the first run, each client runs mcode --version once; a CLI older than 0.6.3 raises MCodeVersionError.On Windows, the mcode.cmd launcher written by the official installer or by npm / pnpm is followed to the JS entry and Node runtime it runs. An unrecognized .cmd file is rejected; pass the JS entry as bin instead.

Options

Options are dataclasses passed to the client, the Thread, and each Turn.

`MCode(MCodeOptions(...))`

Field	Description
`bin`	Explicit `mcode` path or command name
`data_dir`	Data directory, passed to the CLI as `MINIMAX_DATA_DIR`
`env`	Child process environment. Replaces `os.environ` when set; values are hidden in `repr()`
`config_path`	Runtime config file, passed as `--config`

To add variables instead of replacing the environment, merge os.environ:

import os
from minimax_code import MCode, MCodeOptions

client = MCode(MCodeOptions(env={**os.environ, "FOO": "bar"}))

`start_thread` / `resume_thread(ThreadOptions(...))`

Field	CLI flag
`cwd`	`--cwd`; defaults to the current working directory, resolved when the Thread is created
`model` / `effort`	`--model` (`provider/model`) / `--effort`
`permission`	`--permission`: `smart` / `full` / `off`
`mode`	`--mode`: `standard` / `lightweight`; only on a new Thread
`prompt_mode`	`--prompt-mode`: `tui` / `coding` / `work`
`system_prompt`	Replaces the system prompt (the SDK writes a temporary file)
`append_system_prompt`	Appended to the system prompt (the SDK writes a temporary file)

Invalid values raise MCodeInvocationError before the CLI starts. mode="lightweight" on resume_thread is rejected the same way. There is no ask permission: each Turn is a separate process, so interactive permission prompts are not supported.

`thread.run` / `thread.run_streamed(prompt, RunOptions(...))`

Field	Description
`files`	Attachments (`--file`, repeatable)
`timeout_ms`	Turn timeout, enforced by the CLI
`max_steps`	`--max-steps`

from minimax_code import RunOptions

turn = await thread.run(
    "Diagnose and fix the failing CI job",
    RunOptions(files=["./ci.log"], timeout_ms=10 * 60_000, max_steps=50),
)

A Thread runs one Turn at a time. A concurrent call raises ThreadBusyError; Turns are not queued.

Threads and resume

thread.id is the Session id. It becomes available once the first Turn emits its first event. Persist it and continue later with resume_thread:

thread = client.start_thread(ThreadOptions(cwd="/path/to/project"))
await thread.run("...")

later = client.resume_thread(thread.id, ThreadOptions(cwd="/path/to/project"))
print((await later.run("What did I ask first?")).final_response)

A Session belongs to the workspace it was created in, so pass the same cwd to resume_thread(). When cwd is omitted, the current working directory at that call is used. A Thread pins its cwd when it is created, so a later os.chdir() does not affect it. Resuming from a different workspace fails with MCodeRunError, and retrying does not help.

Streaming

run_streamed() returns a StreamedTurn that you iterate with async for. Text deltas for an agent_message can arrive on item.started as well as item.updated, so read contentDelta from any event that carries an item:

streamed = await thread.run_streamed("Fix the failing test.")
async for event in streamed:
    item = event.get("item")
    if item and item["type"] == "agent_message":
        print(item.get("contentDelta", ""), end="")
    elif event["type"] == "turn.failed":
        print("failed:", event.get("error"))

Events are the CLI’s stream-json events as plain dicts, passed through unchanged, unknown types included: exec.started, session.started / session.resumed, turn.started, item.started / item.updated / item.completed, turn.completed, turn.failed, and exec.completed. The one exception: an item.updated snapshot (no contentDelta) identical to the previous snapshot of the same item is skipped. Text deltas are never skipped.turn.failed is an ordinary event. Iteration raises only for process or protocol failures.Turn.items are normalized dataclasses: AgentMessageItem, ReasoningItem, and ToolCallItem. Items that had no item.completed when the Turn ended have incomplete=True.

Errors

Every error subclasses MCodeError, which carries exit_code, stderr (the CLI stderr tail, for diagnostics only), session_id, result, and items.

Error	Typical cause
`MCodeInvocationError`	An option the SDK rejects before starting the CLI, or CLI exit code `2`
`MCodeRunError`	The Turn ended with `failed`, `timeout`, or `limit_exceeded`; adds `status` and `category`
`MCodeAbortError`	The Turn was cancelled (exit code `130` or a cancelled result)
`MCodeProtocolError`	Non-JSON stdout, missing `exec.completed`, broken pipe, and similar
`MCodeNotFoundError`	No CLI found
`MCodeVersionError`	CLI older than `0.6.3`, or an unsupported event `schemaVersion`
`ThreadBusyError`	Concurrent Turn on the same Thread

MCodeRunError.status is failed, timeout, or limit_exceeded. category is config, runtime, internal, or None. MCODE_EXEC_EXIT_CODES maps the CLI exit codes by name.

from minimax_code import MCodeAbortError, MCodeError, MCodeRunError

try:
    turn = await thread.run("Run the migration")
except MCodeRunError as error:
    print(error.status, error.category, error.exit_code, error.session_id)
except MCodeAbortError:
    print("cancelled")
except MCodeError as error:
    print(type(error).__name__, error)

The SDK never retries automatically. When an error carries session_id, you can continue with resume_thread(error.session_id, ...). Errors can be pickled, for example to return them from a ProcessPoolExecutor worker.

Cancellation and timeouts

streamed.cancel() sends SIGTERM, the CLI’s cancel signal. The stream then ends with the CLI’s final events;
Leaving the async for early (break or an exception), or cancelling the task running thread.run(), stops the CLI: SIGTERM, then SIGKILL if it is still running after the CLI’s 60-second shutdown budget. The next Turn on the same Thread waits for that shutdown instead of raising ThreadBusyError;
async with streamed: or await streamed.aclose() stops the CLI deterministically;
timeout_ms is enforced by the CLI. If the CLI is still running 90 seconds after timeout_ms, the SDK kills it and raises MCodeRunError with status="timeout";
On Windows, cancellation stops the CLI immediately.

streamed = await thread.run_streamed("Refactor the module")
async with streamed:
    async for event in streamed:
        if event["type"] == "item.completed":
            break  # leaving the block stops the CLI

Not available yet

Interactive permission prompts (permission="ask") and custom in-process tools;
output_schema (structured-output constraints), approval callbacks, steering a running Turn, and forking.

For direct CLI usage or structured output, see Headless and CI.

​Requirements

​Installation

​Quick start

​Blocking API

​CLI resolution

​Options

​MCode(MCodeOptions(...))

​start_thread / resume_thread(ThreadOptions(...))

​thread.run / thread.run_streamed(prompt, RunOptions(...))

​Threads and resume

​Streaming

​Errors

​Cancellation and timeouts

​Not available yet