# MiniMax Code English | [简体中文](./README.zh-CN.md) **An AI coding agent for your terminal.** MiniMax Code understands your codebase, edits files, runs commands and tests, and keeps the work in resumable Sessions. Use it as an interactive TUI, run it headlessly in scripts and CI, or connect it to an ACP-compatible client. ## Quick start Requires Node.js `22.19+` on Node 22, or Node.js `24–26`. ```bash npm install -g @minimax-ai/code --allow-scripts=@minimax-ai/code,better-sqlite3 --registry=https://registry.npmjs.org/ cd your-project mcode ``` Then describe the outcome you want: ```text Find the cause of the intermittent 500 error in the login endpoint, fix it, and run the relevant tests. ``` MiniMax Code will inspect the repository, make the requested changes, run the checks it can, and summarize what it verified. ## Why MiniMax Code | Capability | What it gives you | | ---------------------- | ---------------------------------------------------------------------------------------- | | Codebase understanding | Search files, trace call paths, explain architecture, and identify impact before editing | | End-to-end execution | Edit code, run commands, and verify changes with the repository's own tools | | Resumable work | Keep each task in a Session and continue where you left off | | Human control | Review plans and choose how much access the agent has before sensitive operations | | Flexible workflows | Work interactively, automate with structured output, or integrate over ACP | | Extensibility | Choose models and Providers, and add new capabilities with Plugins | ## Use it your way ### Interactive TUI Start in the current directory: ```bash mcode ``` Or start with a task already attached: ```bash mcode "Explain this repository and identify the highest-priority technical debt." ``` While MiniMax Code is working, press `Enter` to steer the active turn or `Alt+Enter` to queue a follow-up for the next turn. Use `Alt+Up` (or `Shift+Left`) to move the latest queued message back into the Composer before steering it with `Enter`. Useful Session commands: ```bash # Continue the latest Session for this workspace mcode --continue # Browse Sessions or open one by ID mcode --session mcode --session ``` Inside the TUI, `/sessions` opens the Session Center for recent/archived Sessions, workspace/all scope, rename, archive/restore, and search. Search accepts plain text plus `id:`, `path:`, `type:`, `status:`, and `model:` filters. `/history` opens the current Session's input history and lets you preview a safe fork, edit, conversation rewind, or conversation-and-files rewind using the existing confirmation flow. While a response is running, history remains browse-only. Inside the TUI, use `/export` to save the current Session as Markdown. Use `/review` to review staged, unstaged, and untracked changes in the current workspace. The Transcript shows either a passing summary or findings with file locations. 使用 `/btw [question]`（或 `/side [question]`）可在主任务继续运行时打开临时侧会话。 Runtime 从已持久化历史选择最近的完整前缀：工具调用已有全部结果时一起保留；结果未齐时回退到 该组调用之前。创建时固定这个位置，主任务后续追加输出不会改变本次侧会话继承的历史。 侧会话把继承历史作为参考上下文；已有工具调用不会重新执行。侧会话沿用主会话的权限模式， 仅在用户明确要求时修改工作区；Full access 不新增确认，其他模式继续执行原有权限规则。 按 `Ctrl+/` 切换主会话和侧会话，或用 `/parent` 返回主会话。侧会话底栏显示主任务状态。 在空输入框按 `Ctrl+C` 会关闭并丢弃侧会话；返回主会话后再次执行 `/btw` 会创建新的侧会话。 临时侧会话不出现在 `/sessions` 或 `/resume` 中，导航到其他会话时会被清理。 历史边界尚未准备好时显示等待提示。创建或加载失败时，诊断上传中的 MCode observability 日志 记录 `session.side.failed`，包括 `create` / `activate` 阶段、会话 ID 和经过脱敏、长度限制的异常原因链。 A no-argument TUI slash command runs only when no message text follows its name (trailing whitespace is allowed). If text follows, the entire line is sent as a regular prompt. Commands that accept arguments continue to run as commands. The Composer labels live input as `Prompt`, `Command`, or `Skill` and adjusts its Enter action so the submission behavior is visible before sending. For example, `/context` is a command while `/context explain this repository` is a prompt; a Skill such as `/docs explain the API` remains a Skill invocation with instructions. Agent Team and Runtime background work share one severity-aware `Tasks` summary line above the Composer, so a long-running Session does not lose input space as work accumulates. Use `/tasks` to open the unified detail view. It lists every task and its state, opens Agent child transcripts with Enter, retains recent completed Runtime tasks after their results are delivered, and exposes task metadata without taking ownership of task state. Delivered history does not keep the Composer summary visible. `Ctrl+T` continues to open the Todo plan. Background task details show errors first and wrap the full Bash command while preserving source line breaks. Use PgUp/PgDn to scroll and Esc to return. Older tasks without stored command source show only their existing Description. ### Headless and CI `mcode exec` runs a task without opening the TUI: ```bash # Run one task mcode exec "Review the current changes and run the relevant tests." # Choose a repository and attach supporting context mcode exec --cwd ./repo --file error.log "Find the cause of this build failure." # Produce machine-readable output mcode exec --output-format json "Summarize the current branch." # Raise the reasoning effort for this Run only mcode exec --model custom_provider:work/deep-reasoner-1 --effort xhigh "Plan this migration." # Review local changes in a workspace mcode exec review --cwd ./repo ``` `--effort` sets the reasoning effort for this Run only and is independent of `--model`. Used alone it applies to the Session's current model. The level is validated against the model's advertised effort levels before the Turn starts, so an unsupported level or a model without effort support fails with a non-zero exit code instead of running at some other strength. The override is never written back to the Session, so resuming with `--session` or `--continue` restores the Session's own level. An effort level is not a model variant. `--model provider/model#xhigh` still runs, unchanged, but Runtime reads the suffix as part of the model identity and applies its own default strength, so the requested level is silently dropped. Use `--effort xhigh` whenever the level has to take effect. For automation, `--output-schema` accepts an inline JSON object or file path and constrains the model's final answer for Anthropic Messages, OpenAI Responses, and Chat Completions. The outer `--output-format json` value remains a stable `ExecResult`; models without strict Structured Output support fail before the Turn starts. `--output-last-message` is written atomically only after the final answer passes validation and Runtime completes its bounded shutdown. Use `--output-format stream-json` to stream progress. `mcode exec review` always reviews staged, unstaged, and untracked local changes. It supports `--cwd`, `--model`, `--effort`, `--config`, `--permission`, `--timeout`, `--max-steps`, `--output-format`, and `--output-last-message`. Findings exit with code `0`; invocation, Runtime, or invalid Review result failures use a non-zero exit code. Use `--prompt-mode` to select `tui` (default), `coding`, or `work` for a benchmark: ```bash mcode exec --prompt-mode work "Complete this evaluation task." ``` The mode selects one complete system template, including identity and rules. Inline Memory instructions follow the current switches. Bundled Prompt contents are fixed for the process, while tools and permissions follow the TUI configuration. Evaluation snapshots include the actual Prompt, mode, version, and content hashes. A resumed Task must have a saved matching mode; start a fresh benchmark Session for older Tasks without that information. This option applies to regular `exec` tasks. Run `mcode exec --help` for the complete set of headless options. ### Browser operations The interactive TUI, `mcode exec`, and ACP share the same in-process Runtime lifecycle. The native headless Browser Provider lets the agent navigate pages, inspect interactive elements, click, type, scroll, capture screenshots, and trigger or observe downloads while a single Browser tab is alive. Downloaded files remain provider-internal and are not yet returned as reusable local assets. Browser Use tooling is off by default and must be enabled explicitly. The optional Browser section only selects a Chrome executable: ```yaml # $MINIMAX_DATA_DIR/config.yaml beta: browserUseTooling: true browser: chromePath: /Applications/Google Chrome.app/Contents/MacOS/Google Chrome ``` When Chrome can be discovered from the platform defaults, omit `browser.chromePath`, but keep the explicit Browser Use opt-in: ```yaml beta: browserUseTooling: true ``` ```bash MINIMAX_DATA_DIR=/tmp/mcode-browser-real mcode ``` Then ask the TUI, for example: ```text Use Browser to open https://example.com, report the page title, and capture a screenshot. ``` Use the same command shape with `mcode exec "..."` for non-interactive runs. `MCODE_CHROME_PATH` may override `browser.chromePath` for one launch. macOS, Linux, and Windows otherwise discover common Chrome/Chromium installations automatically. `MCODE_BROWSER_BACKEND` is no longer required and does not control enablement. On Linux root, the provider automatically adds Chrome's `--no-sandbox` flag so Browser remains available without extra configuration. Non-root Linux launches retain Chrome's process sandbox. Native Headless exposure requires `beta.browserUseTooling: true`; `beta.filePanelBrowser` gates only the Electron FilePanel provider. Model-facing `navigate` and `open_tab` actions accept HTTP(S) URLs only. Local or inline schemes such as `file:` and `data:` are rejected before Chrome starts; local files must enter Browser upload through the workspace-authorized file input path. ### ACP clients Start the Agent Client Protocol server over stdin/stdout: ```bash mcode acp ``` ACP-compatible editors and agent clients can use it to create, load, resume, and close MiniMax Code Sessions. Enabled installed Skills appear alongside native slash commands, scoped to the attached Session's Agent and workspace. Names that conflict with native commands or cannot be invoked are omitted. Skill discovery does not block native command discovery. ## Models, Providers, and Plugins Local settings updates reject malformed YAML and non-mapping configuration documents without replacing the original `config.yaml`. Repair the file before retrying the settings change. Sign in with MiniMax: ```bash mcode login ``` Desktop and the CLI/TUI share the same OAuth Core credential namespace when their canonical `dataDir`, build environment, region, and client ID match. Runtime receives only an in-memory access token projection. Installing `@minimax-ai/code` installs both the `mcode` and `mcode-tools` commands; the latter does not depend on starting the TUI to appear on `PATH`. Inside a TUI-owned process, `mcode-tools` obtains short-lived access-token leases from the TUI Auth Lease Broker. It does not read the host `auth.json`, persist refresh tokens, or expose a second login/logout flow. The command remains installed regardless of login state; without a shared MCode login, brokered calls fail with an authentication-required error. A direct `mcode-tools` invocation outside a TUI-owned process remains available; TUI does not rewrite that process's environment or configuration. Internal `test` and `staging` builds can route OAuth and managed-backend requests through an explicit lane. Put the global option before the subcommand: ```bash mcode --lane oauth2 login mcode --lane oauth2 mcode --lane oauth2 exec "Verify the OAuth session" ``` Production builds reject `--lane`, and MCode does not infer it from environment variables. When you switch providers or models in an existing conversation, the Transcript shows a yellow notice that the existing prompt cache may not be reusable and additional costs may occur. Initial selection, reselecting the same model, and reasoning-only changes do not show this notice. Use `/model` in the TUI to select a model and reasoning level. Select `Add 3rd-party provider…` to search models.dev or configure a Custom Provider. API keys stay masked in the form, and Runtime tests the connection before saving and applying the selected model. Use the Provider commands to inspect or configure model sources: ```bash mcode provider list mcode provider test mcode provider add --name --base-url --model mcode provider remove --yes ``` Browse and manage Plugins from the command line: ```bash mcode plugin list --available mcode plugin add mcode plugin enable mcode plugin disable ``` Run `mcode plugin` without arguments to open the interactive Plugin manager. ## Network proxy MiniMax Code reads `HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY`, and `NO_PROXY`, including their lowercase variants: ```bash export HTTPS_PROXY=http://127.0.0.1:7890 mcode ``` `localhost`, `127.0.0.1`, and `::1` always bypass the proxy. ## Plans and permissions Plan Mode lets you review an implementation plan before any code changes begin. Permission modes let you choose the right balance between confirmation and autonomy for the current task: - **Ask** requests confirmation before operations that need approval. - **Auto** handles routine operations automatically and asks when needed. - **Full access** allows broader execution for environments where you already trust the task and workspace. Keep the narrowest mode that still fits your workflow, especially when working in an unfamiliar repository. ## Command reference | Command | Purpose | | ------------------------ | ------------------------------------------------------ | | `mcode [prompt]` | Start the interactive TUI | | `mcode --continue` | Continue the latest Session for the current workspace | | `mcode --session [id]` | Browse Sessions or open one by ID | | `mcode exec [prompt]` | Run a headless task | | `mcode exec review` | Review staged, unstaged, and untracked changes | | `mcode init [directory]` | Analyze a repository and create or improve `AGENTS.md` | | `mcode login` / `logout` | Manage MiniMax authentication | | `mcode provider ...` | Manage model Providers | | `mcode plugin ...` | Browse and manage Plugins | | `mcode acp` | Start the ACP server | | `mcode update` | Check for and install updates | Run `mcode --help` or `mcode --help` for all options available in your installed version. See [CHANGELOG.md](./CHANGELOG.md) for user-visible changes in stable releases. ## Troubleshooting
mcode: command not found Make sure the global npm bin directory is in `PATH`, then run: ```bash npm list -g @minimax-ai/code --depth=0 npm prefix -g ```
Unsupported Node.js version Supported versions are Node.js `>=22.19 <23` and `>=24 <27`. Node 23 is not supported. After switching Node.js versions, reinstall MiniMax Code: ```bash node --version npm install -g @minimax-ai/code --allow-scripts=@minimax-ai/code,better-sqlite3 --registry=https://registry.npmjs.org/ ```
npm 12 blocks installation scripts, or startup reports a missing native SQLite dependency npm 12 blocks unapproved installation scripts by default. If `npm warn install-scripts` lists MCode's `postinstall` and `better-sqlite3`'s `install` as blocked, SQLite may be unavailable even when npm reports `added` or `changed packages`. Startup may report `Could not locate the bindings file`, a missing `better_sqlite3.node`, or an outer `migration_failed` error. For official Shell/PowerShell installations, rerun the original installer command. The installer and `/update` handle the required script options and native dependencies. If MCode cannot start, repair it with the installer first. For `npm install -g` installations, prefer the repair command printed in the startup error. Use the following command when installing `latest`: ```bash npm install -g @minimax-ai/code@latest --registry=https://registry.npmjs.org/ --foreground-scripts --ignore-scripts=false --include=optional --allow-scripts=@minimax-ai/code,better-sqlite3 ``` Keep the package name, version, and registry from the original installation command. For a Preview or pinned installation, retain the exact version instead of switching to `latest`. List the same MCode package name and `better-sqlite3` in `--allow-scripts`. Setting `--ignore-scripts=false` alone does not approve scripts in npm 12; `--include=optional` ensures the SQLite dependency is installed. Start `mcode` after `[MCode] Native SQLite check passed.` appears. This repairs native dependencies in the installation directory and preserves existing configuration and Sessions. If it still fails, provide the complete new installation log and the output of `node --version` and `npm --version` to investigate download, build, or runtime errors.
Authentication or Provider problems Check the installed version, sign-in state, and Provider connectivity: ```bash mcode --version mcode login mcode provider list mcode provider test ```
## Update and uninstall ```bash # Check for and install updates mcode update # Uninstall npm uninstall -g @minimax-ai/code ``` ## License MIT ## 项目级 MCP Runtime 自动加载会话主工作目录的 `.mcp.json`，与 Desktop、exec、ACP 共用配置规则；详见[项目级 MCP 配置](../local-runtime-v2/docs/project-mcp.md)。 ### 公开 v0.5.0 后续修复回流 - 欢迎页按当前 Provider 判断登录需求：BYOK 无 MiniMax 账号仍可 Ready；配置警告保留 `/provider` / `/status` 提示。 - CLI/TUI 的本地会话标题按所选模型决定审核策略；BYOK 不要求托管账号，官方托管模型、未知路由及 Desktop 保留既有审核。Task 使用持久化的冻结模型定义。 - Z.AI / 智谱预设区分 API 与 Coding Plan；模型选择页可用 `ctrl+e` 修改 Base URL 后重试，失败不保存且保留 key/model 草稿。智谱 token 计数保持所选套餐路径。 - 普通模式的队列更新若改变已滚出正文，会重建完整投影；仅样式变化不重放历史。Windows 的硬件光标默认保持可见，并在同步帧呈现前恢复输入位置；显式配置仍优先。 - 无 bracketed-paste framing 的单个多行纯文本 chunk 整体进入编辑器，不逐行提交。跨 chunk 和控制序列不作推测。