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

[johnlam1968]

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:

1. 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.
2. 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.

[johnlam1968]

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

1. 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).

2. 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).

3. 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:

1. 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.
2. 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).
3. Add mcode team validate <roster.yaml> (small CLI
   surface) so users can lint their planned split without
   launching a real session.
4. 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.

[johnlam1968]

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:

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

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

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