[Feature]: Expose mavis orchestrator via mcode exec --team (CLI parity with Desktop GUI Team button)

Problem

mcode exec (v0.2.6, verified 2026-08-27) is a single-agent executor with no native multi-agent dispatch. The Desktop GUI has a Team button that triggers mavis to orchestrate sub-agents, but the CLI does not.

Why this matters strategically

Exposing the full power of mcode via the CLI is not just a parity
fix — it is what lets MiniMax realize the maximum capability of this
harness and of MiniMax as a platform company.

The whole point of an agent harness is to give a single human (or
agent) leverage: instead of writing code, you describe a goal and the
harness coordinates the work. Today, the harness coordinates only
one agent through the CLI — the moment a task needs a writer +
verifier + synthesist (which is most real research, code-review,
ingest, and data-pipeline work), the user is pushed into either GUI
mode or fragile shell-fan-out. Neither scales.

If the CLI exposes mavis's orchestrator the way the GUI Team
button already does, then any human — or any other agent — can have
an agent team enabled, harness-controlled complex job achieved, by
simply entering a line of CLI code:

mcode exec --team roster.yaml -o final.md "verify this filing"

That single line replaces:

A click path through the Desktop GUI.
A hand-written orchestration prompt that encodes five different
sub-agent instructions, output paths, wait conditions, and
handoff rules.
A bespoke shell script that launches N parallel mcode exec
processes and tries to glue their outputs back together.

Making the CLI a first-class surface for multi-agent work turns
mcode from "a coding agent with a team mode" into "an agent
harness that any user can drive end-to-end from a terminal or from
another agent". That is the version of the product that earns the
"platform" framing — and it is the version that agents (including
MiniMax-built ones) can call without permission-grants, without GUI
sessions, and without ad-hoc wrappers.

The GUI Team button is the proof of concept; the CLI flag is what
makes it platform-grade.

Reproduce the missing flag:

$ mcode exec --team
error: unknown option '--team'
$ mcode exec --agent verifier
error: unknown option '--agent'

The only flags available are --config / --cwd / --input-format / --max-steps / --output-format / --output-last-message / --output-schema / --permission / --timeout / --model / --session / --continue / --input / --file. There is no --team, no --agent-profile, no --orchestrator, no --subagent-roster.

This forces any CLI user who wants multi-agent work (e.g. writer→verifier→synthesist, ingest pipelines, parallel scrapers with handoff) to either:

Encode the entire sub-agent plan into the prompt — including the names, output paths, "wait for all sub-agents before synthesizing", and disjoint file-ownership rules. If any of those five instructions is missing, the main agent silently does all the work itself and the deliverable looks like multi-agent evidence but isn't.
Shell-level fan-out of N parallel mcode exec processes — no shared coordinator, no handoff log, no synthesis visibility. This is the failure mode I hit on 2026-08-27 (launched 4 parallel execs for a verification task; 2 sub-agents failed silently; the synthesist had no inputs and did the work inline, producing a report that looked tier-tagged but wasn't).

Both options are worse than what the GUI Team button does. They are also worse than what mavis's internal Task tool already does when a parent agent delegates to a child — the runtime clearly knows how to manage sub-agent lifetime, handoff logging, foreground/background discipline, and disjoint ownership (delegation.md.hbs in the dist). The CLI just has no entry point into that machinery.

Proposed solution

Expose the existing mavis orchestrator behind CLI flags. At minimum:

# Sub-agent roster as JSON / YAML file (or inline)
mcode exec \
  --team agents.yaml \
  --cwd ~/work/dennis-1988 \
  --model minimax/MiniMax-M3 \
  --permission smart \
  --max-steps 25 \
  --timeout 8m \
  -o final.md \
  "Verify Richard Dennis's 1988 inflation claims across historian + economist sub-agents"

# agents.yaml (or .json) example
roster:
  - name: verifier
    role: source-integrity
    output: verifier.md
  - name: historian
    role: data-pull
    output: historian.md
    background: true
  - name: economist
    role: causal-logic
    output: economist.md
  - name: synthesist
    role: synthesis
    waits_for: [verifier, historian, economist]
    output: final.md
synthesis:
  wait_for_outputs: [verifier.md, historian.md, economist.md]
  handoff_log_required: true
  final_file: final.md

Behaviors the GUI Team button already implements and that the CLI should reuse:

Sub-agent lifetime managed by mavis (spawn → work → return → terminate), all in the same session / workspace / scratchpad.
Handoff log enforced by the runtime, not left to the prompt.
Foreground / background discipline — background: true only for independent work; parallel writers must have disjoint file ownership.
Task registry — sub-agent work auditable via mavis session list / session messages.
Per-sub-agent model — model: field in the roster, instead of inheriting the parent --model.

What the CLI should NOT have to invent:

A new orchestrator. Reuse mavis's Task tool dispatch.
A new handoff format. Reuse the existing delegation.md.hbs template.
A new model-routing layer. Reuse the existing --model plumbing.

The CLI change is essentially: add --team <file> (or --team <inline-json>), have mcode exec instantiate mavis as the parent, and have mavis fan out per the roster.

Optional follow-ups that would also help:

mcode team list / mcode team validate agents.yaml — schema-check the roster before launch.
mcode team init <name> — scaffold a new agent template under ~/.mcode/agents/<name>/ (mirroring the assets/agents/verifier/ / worker/ / explore/ built-ins).
Document the existing CLI gap in docs/code/cli/quick-start so users don't waste hours encoding multi-agent plans into single-agent prompts.

Platform

macOS
Windows
Linux desktop support
All desktop platforms

Additional context

MiniMax Code v0.2.6 (CLI), installed via npm.
mavis delegation.md.hbs already encodes the rules the CLI would need: foreground when result blocks next decision; background only for independent / long-running work; parallel writers must have disjoint ownership; the child does not inherit conversation history — the parent must brief it with objective / known facts / scope / acceptance criteria / output format.
Failure case that produced this request: 2026-08-27 verification of Richard Dennis's mid-1988 inflation claims in Market Wizards. Launched 4 parallel mcode exec calls — historian and economist sub-agents returned with Runtime completed without a final assistant response and Web search is down; the synthesist had no inputs and did the work inline, producing a 15KB "synthesis" that looked tier-tagged but wasn't. The whole failure is a direct consequence of the CLI not exposing mavis's orchestrator.
I have not seen any open issue requesting this exact CLI feature. Searched: cli subagent, --team, --agent, orchestrate. Closest match is [v3.0.48] Removed mavis CLI but did not add native tool injection — configured MCP servers unreachable from agent #120 (mavis CLI removal) and [Feature]: 希望未来的cli版本能支持web模式 #101 (web mode), neither covers team-mode CLI.

Before submitting

I have searched existing issues.

Update 2026-09-06 — `--team` is not needed; team behavior is prompt-driven

I ran an end-to-end verification of mcode exec against
@minimax-ai/code@0.3.4 (latest, published 2026-09-06) and the
team behavior already works on the CLI — but it is
prompt-driven, not flag-driven. No --team is needed; the
flag design in this issue is solving a problem the runtime
already solved differently.

What I verified

mcode exec "..." boots as the mavis orchestrator by
default (no flag, no config). The first system reminder in
every session is:
```
<agent-context>
  agent: Mavis
  agentName: mavis
  agentRole: orchestrator
  SESSION ROLE: root
  YOUR AGENT CONFIG DIRECTORY: /home/john/.minimax/agents/mavis
</agent-context>
```
Persisted session example:
~/.minimax/v2/sessions/2026/09/06/16-40-27-563-…/messages.jsonl
(orchestrator mvs_a20984951d6247dfbed66d49aaed01ed).
The orchestrator's tool list (verified by direct mcode exec
probe) includes a task tool that spawns peer agents:
```
{
  "tools": ["bash", "edit", "glob", "grep", "read", "skill",
            "task", "task_append", "task_output", "task_query",
            "task_stop", "todowrite", "update_goal",
            "web_fetch", "web_search", "write"]
}
```
Peer agents are spawned by calling task with
agent_name: "worker" | "verifier" | "explore" | "code-reviewer",
and the result is a <task_result> with a real
session_id: mvs_… for the peer (a branch session under the
same workspace).
I ran a two-phase audit (worker draft → verifier audit)
and the orchestrator successfully:
- spawned a worker peer that wrote
  /tmp/mcode-test/phase1-draft.md (2536 bytes, 5 bullets on
  HKEX Appendix D2 Note 2.1);
- waited for the peer's <task_result> inline
  (run_in_background: false);
- spawned a verifier peer that started the audit (timed out
  under --max-steps 30, which is the step-budget finding
  below).
All three sessions — orchestrator + worker + verifier — are
persisted under ~/.minimax/v2/sessions/2026/09/06/…, and the
peer sessions have agentRole: worker, SESSION ROLE: branch,
PARENT SESSION: <orchestrator-id>. So sub-agent lifetime,
handoff log, and disjoint workspace are all already handled by
the runtime — without a --team flag.

What's actually missing (and what `--team` would buy)

A --team <roster.yaml> flag is still useful, but for a
different reason than I originally wrote: discoverability
and budgeting, not capability. Today:

Capability is there — just hidden behind prompt
engineering. You have to know the task tool's input shape,
which peer names are available, and how to write the
orchestration prompt. The web/desktop UI ships a team skill
that packages this; the CLI does not (see [Bug] /docs/cli/integrations documents 'mcode app-server' subcommand, but no released @minimax-ai/code version (≤ 0.3.4) ships it #139-adjacent
finding in the new mcode skill §2.5.10).
Budgeting is invisible. The orchestrator consumes 1–2
steps per task call plus a fixed startup cost. A 3-peer team
with each peer doing ~5 internal steps needs ~25 orchestrator
steps total. The default --max-steps 30 is too tight and
silently cancels mid-fan-out (which is what hit me in the
verification). A --team flag could compute and apply the
right budget automatically, instead of asking the user to
reason about it.
Roster validation has no CLI surface. If you mistype
agent_name: "verfier", the orchestrator falls back to a
default and silently does the work itself — the failure mode
this issue is trying to prevent. A mcode team validate /
--team validate step would catch this at launch time.

Suggested change of shape (less ambitious, more useful)

If the team agrees, I'd re-scope this issue to:

Document that mcode exec is already a multi-agent
runtime and the task tool is the entry point. The web
desktop docs implicitly assume this; the CLI does not. A new
docs/code/cli/team-mode page (or a section in
quick-start) closes the gap.
Ship a mavis-team skill in assets/skills/ that the
user can load via mcode plugin enable or by dropping a copy
into ~/.minimax/.builtin-skills/mavis-team/SKILL.md. The
skill would be a worked example of an orchestration prompt
(worker + verifier + compose), so the user doesn't have to
author it. This is what the web/desktop team button
effectively packages (see mcode skill §2.5.10).
Add mcode team validate <roster.yaml> (small CLI
surface) so users can lint their planned split without
launching a real session.
Add --team-budget (or auto-compute) that derives
--max-steps and --timeout from the roster's peer count
and per-peer step estimate.

I am not opposed to --team roster.yaml itself — the
roster file shape I proposed is fine — but the flag would only
get exercised by users who already know about mavis and the
task tool. The lower-effort wins above move the same needle
for many more users.

Evidence

New mcode skill §2.5 (verified 2026-09-06): describes the
mavis orchestrator, the task tool shape, the two-layer agent
taxonomy (mavis / worker / verifier / explore / code-reviewer
with agentRole: orchestrator | worker), the cost / step
budget table, and the verified recipe for mcode exec with a
mavis-team prompt.
Live session tree from my test (3 sessions, persisted under
~/.minimax/v2/sessions/2026/09/06/):
- Orchestrator: mvs_a20984951d6247dfbed66d49aaed01ed
- Worker peer: mvs_6aff16058f8242ea91badac8730ac24e
- Verifier peer: mvs_f9eb82dff9454815ad6c637209080440
Related issue: [Bug] /docs/cli/integrations documents 'mcode app-server' subcommand, but no released @minimax-ai/code version (≤ 0.3.4) ships it #139 (the mcode app-server tracking
issue); the built-in team skill on web/desktop but missing
on CLI is the same kind of "packaged affordance" gap.
mcode skill §2.5.10 documents the web/desktop vs CLI
built-in-skill diff in detail.

Happy to draft a PR for any of items 1–4 if maintainers want
to pursue this direction.

Follow-up 2026-09-06 — confirmed: `cat team-skill.md | mcode exec` works end-to-end

I just verified the pipe-a-skill-into-stdin pattern. It works,
and it's the cleanest "team mode from the CLI" recipe I can
imagine — no new flag required.

Verified recipe

# 1. Author a "team skill" as a markdown file
cat > team-skill.md <<'SKILL'
---
name: team-mode-demo
description: |
  Spawn a worker peer to draft, then a verifier peer to audit,
  then a final-summary step. Use when the user wants a
  worker + verifier fan-out.
---

# Team Mode Demo (worker + verifier)

You are the mavis orchestrator. For any input the user gives after
loading this skill:

1. Spawn a `worker` peer to draft a 3-bullet summary of the input.
   The worker must:
   - Write the draft to `/tmp/mcode-test/team-demo-draft.md` using
     only training-data knowledge.
   - Not verify its own draft.
   - Report back a one-line confirmation.

2. Spawn a `verifier` peer to audit the draft. The verifier must:
   - Read the draft.
   - Mark each bullet [OK] / [WARN] / [FAIL].
   - Write the audit to `/tmp/mcode-test/team-demo-audit.md`.
   - Not fix the draft.

3. Compose a 1-paragraph final summary to
   `/tmp/mcode-test/team-demo-final.md`.

Use `task` with `run_in_background: false` so you wait for each peer.
Set `--max-steps 60` and `--timeout 5m` to leave room for 3+ internal
steps per peer.

Do NOT do the work yourself; the user asked for a team.
SKILL

# 2. Pipe the skill + user task into mcode exec
{ cat team-skill.md; echo; echo "USER TASK: Compare the value of the capital of France, Japan, and Brazil."; } \
  | mcode exec \
      --max-steps 60 \
      --timeout 5m \
      --permission off \
      --output-format text \
      -o final-output.md \
      --input - \
      --input-format text

Verified result (just ran this on 0.3.4)

team-demo-draft.md written by worker peer (525 bytes, 3 bullets)
team-demo-audit.md written by verifier peer (1282 bytes, all
3× [OK], overall PASS)
team-demo-final.md composed by mavis orchestrator (976 bytes)
Persisted session tree under ~/.minimax/v2/sessions/2026/09/06/:
- Orchestrator: mvs_1d54978b145941cda116f23314b8cb49 (parent)
- Worker peer: mvs_d83d9a2fa12467a0816444440531… (branch)
Tool calls: 4× task (all agent_name: worker / verifier,
all run_in_background: false), plus the orchestrator's
standard read / bash / write / todowrite / grep set.

So the user's instinct is right: the pipe-into-stdin pattern is
the CLI's "Team" button. No --team roster.yaml is needed for
the basic case; the existing --input - / --input-format text
flags already accept the skill content.

Where a flag would still help (revised, lighter than my original ask)

A --skill <name> flag would be useful for two things the
pipe pattern can't do cleanly:

Frontmatter validation. The pipe pattern silently accepts
any markdown. A --skill <name> flag could look up
~/.minimax/.builtin-skills/<name>/SKILL.md (or
~/.agents/skills/<name>/SKILL.md) and validate the YAML
block before launch. The user gets a mcode: error: skill 'foo' frontmatter invalid: missing 'description' instead of
a confused orchestrator.
Loading the skill's references/ and scripts/ into the
orchestrator's working set. Today, only the SKILL.md text
is injected via --input. A --skill flag could mirror the
web/desktop loader: copy references into the workspace, make
scripts available, announce availability in the system
reminder. Without this, a skill that ships helper scripts
cannot use them.
Determinism. A --skill flag makes the invocation
"this is a skill run" explicit, so the orchestrator can
be tuned to honor it (e.g. always enter team mode, never
skip peer spawns). The pipe pattern can be silently
downgraded by an ambiguous prompt; a flag cannot.

Concrete proposal:

mcode exec \
  --skill team-mode-demo \
  --max-steps 60 \
  --timeout 5m \
  --permission off \
  --output-format text \
  -o final.md \
  "Compare the value of the capital of France, Japan, and Brazil."

# Or pipe + flag together
{ cat extra-context.md; } | mcode exec --skill team-mode-demo \
  --input - --input-format text -o final.md "..."

A minimal v1 of --skill:

Look up <name>/SKILL.md in the discovery paths
(~/.minimax/.builtin-skills/, ~/.minimax/skills/,
~/.agents/skills/, .agents/skills/).
Validate the YAML frontmatter (must have name and
description).
Prepend the SKILL.md body to the user message (equivalent to
cat skill.md | mcode exec --input -).
Optionally copy references/* and scripts/* into a working
subdir and add a <skill-context> block to the system
reminder so the orchestrator knows helpers are available.

Items 2 (loading scripts) and 3 (determinism) are nice-to-haves
that can ship in v1 or be deferred. Item 1 (validation) is the
highest-value part and is ~30 lines of code.

Summary of the revised position

--team roster.yaml (my original proposal in this issue): not
needed. The runtime already does it; the prompt just has to
ask. The pipe recipe above is the CLI equivalent of the web
Team button.
--skill <name> (new proposal): would be a real win, mostly
for validation + script-loading + determinism. Cheap to
implement, useful to anyone shipping a reusable team recipe
as a SKILL.md file.

I am happy to draft either a PR for the validation-only v1 of
--skill, or a docs PR for the cat skill.md | mcode exec
recipe. Whichever the maintainers prefer.

This was generated by AI during triage.

Acknowledged, and the strategic framing is well taken — CLI/Desktop parity for multi-agent orchestration (writer + verifier + synthesist patterns) is a real gap. mcode exec --team-style native dispatch is recorded as a roadmap enhancement. No committed date yet; updates will land here.

Closing as part of a backlog cleanup: this issue was filed more than a month ago against an older release, and the codebase has changed substantially since then. If it still reproduces on the latest version, please open a new issue with the current version and reproduction steps. Thank you for the report!

批量清理积压：该 issue 创建已超过一个月，针对的是较旧版本，代码已有较大变化。如果在最新版本上仍能复现，欢迎附上当前版本号和复现步骤重新提交 issue。感谢反馈！

Navigation Menu

Repository navigation

[Feature]: Expose mavis orchestrator via `mcode exec --team` (CLI parity with Desktop GUI Team button) #135

Problem

Why this matters strategically

Proposed solution

Platform

Additional context

Before submitting

Update 2026-09-06 — `--team` is not needed; team behavior is prompt-driven

What I verified

What's actually missing (and what `--team` would buy)

Suggested change of shape (less ambitious, more useful)

Evidence

Follow-up 2026-09-06 — confirmed: `cat team-skill.md | mcode exec` works end-to-end

Verified recipe

Verified result (just ran this on 0.3.4)

Where a flag would still help (revised, lighter than my original ask)

Summary of the revised position

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

[Feature]: Expose mavis orchestrator via mcode exec --team (CLI parity with Desktop GUI Team button) #135

Description

Problem

Why this matters strategically

Proposed solution

Platform

Additional context

Before submitting

Activity

johnlam1968 commented on Sep 6, 2026

Update 2026-09-06 — --team is not needed; team behavior is prompt-driven

What I verified

What's actually missing (and what --team would buy)

Suggested change of shape (less ambitious, more useful)

Evidence

johnlam1968 commented on Sep 6, 2026

Follow-up 2026-09-06 — confirmed: cat team-skill.md | mcode exec works end-to-end

Verified recipe

Verified result (just ran this on 0.3.4)

Where a flag would still help (revised, lighter than my original ask)

Summary of the revised position

hetaoBackend commented on Sep 21, 2026

hetaoBackend commented on Oct 19, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions

[Feature]: Expose mavis orchestrator via `mcode exec --team` (CLI parity with Desktop GUI Team button) #135

Update 2026-09-06 — `--team` is not needed; team behavior is prompt-driven

What's actually missing (and what `--team` would buy)

Follow-up 2026-09-06 — confirmed: `cat team-skill.md | mcode exec` works end-to-end