Skip to content

mco-org/mco

BranchesTags

Repository files navigation

MCO

MCO Logo

npm version npm downloads GitHub stars License: MIT Python 3.10+ 5 built-in providers evermemos-mcp

MCO — Orchestrate AI Coding Agents. Any Prompt. Any Agent. Any IDE.

MCO equips your primary agent with an agent team: dispatch Claude, Codex, Gemini, OpenCode, and Qwen in parallel to execute tasks, review outputs, and synthesize consensus.

English | 简体中文

Claude Code Gemini CLI Codex CLI OpenCode Qwen Code OpenClaw
Claude Code Gemini CLI Codex CLI OpenCode Qwen Code OpenClaw 🦞
claude gemini codex opencode qwen openclaw

AI coding agents are now standard tools for every developer. But one agent is just one perspective.

Work like a Tech Lead: assign one task to multiple agents, run in parallel, and compare outcomes before acting.

One command. Five agents working at once.

Works with OpenClaw

Running OpenClaw on your machine? It can use MCO as its multi-agent backbone. Just tell OpenClaw what you need:

"Use mco to run a security review on this repo with Claude, Codex, and Gemini. Synthesize the results."

OpenClaw reads mco -h, learns the CLI, and orchestrates the entire workflow autonomously. Your local machine becomes a multi-agent review team — OpenClaw is the manager, MCO is the dispatcher, and Claude/Codex/Gemini/OpenCode/Qwen are the team members.

This works the same way from Claude Code, Cursor, Trae, Copilot, Windsurf, or any agent that can run shell commands.

Demo video (Bilibili): 给 OpenClaw 装上兵权：组建你自己的 AI 军团

What is MCO

MCO (Multi-CLI Orchestrator) is a neutral orchestration layer for AI coding agents. It dispatches prompts to multiple agent CLIs in parallel, aggregates results, and returns structured output — JSON, SARIF, or PR-ready Markdown. No vendor lock-in. No workflow rewrite.

With the rise of agentic coding — led by projects like OpenClaw and the broad availability of Claude Code, Codex CLI, Gemini CLI, and more — every developer now has access to powerful AI agents. MCO takes the next step: instead of relying on a single agent, you orchestrate a team.

MCO is designed to be called by any orchestrating agent or AI-powered IDE — Claude Code, Cursor, Trae, Copilot, Windsurf, or OpenClaw. The calling agent organizes context, assigns tasks, and uses MCO to fan out work across multiple agents simultaneously. For example, OpenClaw running on your machine can call mco review to dispatch code reviews to Claude, Codex, and Gemini in parallel — turning your local setup into a multi-agent review team with a single command. Agents can also orchestrate each other: Claude Code can dispatch tasks to Codex and Gemini via MCO, and vice versa.

One Agent is a Tool. Five Agents are a Team.

No single AI model sees everything. Each model has its own training data, reasoning style, and blind spots. Using just one agent is like having a team of five engineers and only asking one for their opinion.

MCO turns this into a team workflow:

  1. Assign — You give MCO a task and a list of agents. Like a Tech Lead assigning the same code review to five team members.
  2. Execute in parallel — All agents work simultaneously. Wall-clock time ≈ the slowest agent, not the sum.
  3. Review and deduplicate — MCO collects each agent's findings, deduplicates identical issues across agents, and tracks which agents found what (detected_by).
  4. Synthesize consensus — Optionally, one agent summarizes the combined results: what everyone agrees on, where they diverge, and what to do next.

In practice, different agents catch different things:

  • One agent spots a race condition in your async code but overlooks an SQL injection in the ORM layer.
  • Another finds the injection immediately but misses the race condition entirely.
  • A third catches neither of those but flags a subtle memory leak in the resource cleanup path.

These aren't hypothetical — different models genuinely have different strengths. Some are better at security analysis, some at logic flow, some at performance patterns. By running 3–5 agents in parallel on the same codebase, you get a union of perspectives rather than the intersection. The result is a more thorough review than any single agent could produce, regardless of which one you pick.

This principle extends beyond code review:

  • Architecture analysis — different agents surface different design risks and trade-offs
  • Bug hunting — broader coverage across code paths and edge cases
  • Refactoring assessment — multiple perspectives on impact and safety of proposed changes

The question isn't "which AI agent is best" — it's "why limit yourself to one?"

Key Highlights

  • Parallel fan-out — dispatch to multiple agents simultaneously, wait-all semantics
  • Any IDE, any agent — works from Claude Code, Cursor, Trae, Copilot, Windsurf, or plain shell
  • Agent-to-agent orchestration — agents can dispatch tasks to other agents through MCO
  • Dual mode — mco review for structured code review findings, mco run for general task execution
  • Cross-agent deduplication — identical findings from multiple agents are merged automatically with detected_by provenance
  • Consensus engine — merged findings get consensus_score = agreement_ratio × max_confidence plus confirmed / needs-verification / unverified consensus levels
  • Cross-session memory — --memory flag persists findings and agent scores via evermemos-mcp, building institutional knowledge across runs
  • LLM synthesis — --synthesize runs an extra pass to produce consensus/divergence summary across all agents
  • Live terminal streaming — --stream live renders rich real-time terminal progress; --stream jsonl remains available for machine consumers
  • Debate mode — --debate adds a second challenge round where agents critique the merged findings before final ranking
  • Divide mode — --divide files|dimensions splits review work by file slices or review dimensions while preserving the existing merge + consensus pipeline
  • CI/CD integration — --format sarif for GitHub Code Scanning, --format markdown-pr for PR comments
  • Environment health check — mco doctor probes binary presence, version, and auth status for all providers
  • Token usage tracking — --include-token-usage for best-effort per-agent and aggregate token consumption
  • Progress-driven timeouts — agents run freely until completion; cancel only when output goes idle
  • Stateful sessions — mco session for persistent multi-turn conversations with prompt queue and cancellation
  • ACP transport — --transport acp for structured JSON-RPC communication via the Agent Client Protocol
  • Custom ACP agents — --agent NAME COMMAND to register any ACP-compatible binary as a provider
  • Custom agent registry — .mco/agents.yaml, .mcorc.yaml, or ~/.mco/agents.yaml can register shim, ACP, or Ollama-backed agents; inspect them with mco agent list / mco agent check
  • Flexible prompt input — --file path, --file - (stdin), or piped input for non-interactive workflows
  • Quiet mode — --quiet for pipe-friendly output (final text only, no headers)
  • Config files — .mcorc.json (project) and ~/.mco/config.json (global) for persistent defaults
  • Idempotent sessions — mco session ensure creates-or-returns a session in one call
  • Async send — --no-wait returns immediately after queuing a prompt; retrieve results later via session result
  • Ctrl+C cancel — interrupt session send gracefully, automatically cancels the running prompt
  • Chain mode — --chain runs providers sequentially, feeding each provider's output as context to the next for challenge-and-supplement workflows
  • Per-provider perspectives — --perspectives-json assigns different review focus areas (security, performance, maintainability) to each provider
  • Consensus badges — findings show [N/M agree] in parallel mode or [confirmed by N/M] in chain mode to surface cross-agent agreement
  • Session retry with error classification — session dispatch retries retryable errors (timeout, rate limit, network) with exponential backoff; partial output preserved on timeout
  • ACP bidirectional handlers — agents can read/write files and run terminal commands through MCO
  • Extensible adapter contract — uniform interface for any CLI agent, not limited to built-in providers
  • Machine-readable output — JSON, SARIF, or Markdown output for downstream automation

What's New in v0.9

  • Consensus Engine — findings are no longer just deduplicated. Each merged finding now carries:
    • agreement_ratio = detected_by_count / total_providers_ran
    • consensus_score = agreement_ratio × max_confidence
    • consensus_level = confirmed | needs-verification | unverified
  • Real-time terminal mode — --stream live adds a human-friendly TTY renderer while preserving --stream jsonl for automation.
  • Debate round — --debate asks providers to challenge or refine merged findings before the final output.
  • Divide mode — --divide files balances file ownership across providers; --divide dimensions assigns providers to security, performance, maintainability, correctness, and error-handling perspectives.
  • Custom agent registry — MCO can now discover custom agents from .mco/agents.yaml / ~/.mco/agents.yaml, including Ollama-backed local models.

Built-in Providers

Provider CLI Status
Claude Code claude Supported
Codex CLI codex Supported
Gemini CLI gemini Supported
OpenCode opencode Supported
Qwen Code qwen Supported

The adapter architecture is extensible — adding a new agent CLI requires implementing three hooks: auth check, command builder, and output normalizer.

Use Cases

Scenario Command What happens
PR code review mco review --format markdown-pr Multiple agents review in parallel, output a PR-ready comment
Security scan in CI mco review --format sarif Results upload directly to GitHub Code Scanning
Architecture analysis mco run --providers claude,gemini,qwen Multi-perspective architecture assessment
Pre-deploy health check mco doctor --json Verify all agents are installed and authenticated
Consensus decision mco review --synthesize Summarize what agents agree on and where they diverge
Debate findings mco review --debate --providers claude,codex,gemini Run an extra challenge round before final ranking
File division review mco review --divide files Split changed files across providers, balanced by file size
Dimension division review mco review --divide dimensions Give each provider a dedicated review dimension
Persistent code review mco review --memory Findings accumulate across runs; agents learn what's already been flagged
Diff-only review mco review --diff Review only changed files vs main branch
Staged changes review mco review --staged Review only git staged changes
Real-time event stream mco review --stream jsonl JSONL events to stdout as providers execute
Live terminal stream mco review --stream live Rich terminal progress view for interactive TTY sessions
Multi-turn session mco session start --provider claude Persistent session with conversation history
Cancel running prompt mco session cancel my-review Interrupt running + queued prompts immediately
Queue status mco session queue my-review Show running request ID and queue depth
Multi-session broadcast mco session broadcast "prompt" Fan out to all active sessions, aggregate results
ACP transport mco run --transport acp --providers claude Structured JSON-RPC communication with ACP agents
Custom ACP agent mco run --agent mybot "mybot --acp" Register a temporary ACP-compatible agent; works with shim or acp transport
Prompt from file mco review --file prompt.md --providers claude Read prompt from a file instead of inline
Piped prompt cat prompt.md | mco run --providers claude Read prompt from stdin pipe
Quiet output mco run --quiet --providers claude --prompt "..." Print only final text, no headers
Config-driven run (uses .mcorc.json) Persistent project defaults without CLI flags
Idempotent session mco session ensure --provider claude --name dev Create or return existing session
Async prompt mco session send dev "task" --no-wait Queue prompt and return immediately
Retrieve async result mco session result dev 42 Get result of a previously queued nowait request
Chain analysis mco review --chain --providers claude,codex Claude analyzes first, Codex challenges and supplements
Perspective assignment mco review --perspectives-json '{"claude":"security","codex":"performance"}' Each provider focuses on a different review area
List custom agents mco agent list Show built-in + configured custom agents
Check one custom agent mco agent check my-ollama Validate one configured agent or Ollama model wrapper

Note: --debate and --divide are mutually exclusive. Use one workflow at a time.

Debate example:

mco review \
  --repo . \
  --prompt "Review this PR and challenge weak findings before final ranking." \
  --providers claude,codex,gemini \
  --debate

Divide example:

mco review \
  --repo . \
  --prompt "Review this PR for correctness and performance issues." \
  --providers claude,codex,gemini \
  --divide dimensions

Quick Start

Install via npm (Python 3 required on PATH):

npm i -g @tt-a1i/mco

Or install from source:

git clone https://github.com/mco-org/mco.git
cd mco
python3 -m pip install -e .

Run your first multi-agent review:

mco review \
  --repo . \
  --prompt "Review this repository for high-risk bugs and security issues." \
  --providers claude,codex,qwen

Agent-Friendly CLI

MCO's CLI is fully self-describing. Run mco -h or mco review -h to see grouped flags, defaults, and usage examples — all in the terminal. This means any AI agent that can execute shell commands can learn MCO's interface autonomously by reading the help output, without requiring documentation or prior training.

In practice, you simply tell your IDE agent what you want:

"Use mco to dispatch a security review to Claude and Codex, and a performance analysis to Gemini and Qwen — run them in parallel."

The agent reads mco -h, understands the flags, composes the commands, and orchestrates the entire workflow on its own. You describe the intent; the agent handles the rest.

Usage

Review Mode

Structured code review with findings schema. Each provider returns normalized findings with severity, category, evidence, and recommendations.

mco review \
  --repo . \
  --prompt "Review for security vulnerabilities and performance issues." \
  --providers claude,codex,gemini,opencode,qwen \
  --json

Run Mode

General-purpose multi-agent execution. No forced output schema — providers complete the task freely.

mco run \
  --repo . \
  --prompt "Summarize the architecture of this project." \
  --providers claude,codex \
  --json

Doctor

Check that your agents are installed, reachable, and authenticated before running tasks:

mco doctor
mco doctor --json

Output Formats (Review Mode)

Format Flag Use case
Human-readable report --format report (default) Terminal reading
PR Markdown --format markdown-pr Post as GitHub PR comment
SARIF 2.1.0 --format sarif Upload to GitHub Code Scanning
Machine JSON --json Downstream automation

Consensus Engine

MCO v0.9 upgrades review merging from simple deduplication into a consensus analysis layer:

  • agreement_ratio = detected_by_count / total_providers_ran
  • consensus_score = agreement_ratio × max_confidence
  • consensus_level = confirmed | needs-verification | unverified

Meaning of each level:

  • confirmed — at least 50% of providers reported the finding
  • needs-verification — 2+ providers reported it, but under 50% agreement
  • unverified — only one provider reported it

Outputs now surface this consistently:

  • JSON — each finding includes consensus_score and consensus_level
  • SARIF — confidence is mapped from consensus_score
  • Markdown — findings are grouped by consensus level
  • Chain mode — confirmed findings are rendered as confirmed-by instead of agree

Review Coordination Modes

Mode Flag What it does
Parallel default All providers review the same scope independently
Chain --chain Run providers sequentially; each sees prior analysis
Debate --debate Run a second challenge round on merged findings
Divide by files --divide files Evenly distribute files across providers, prioritizing large files first
Divide by dimensions --divide dimensions Keep the same file scope, but assign each provider a review dimension

--divide is mutually exclusive with --chain and --debate.

Result Modes

Mode Behavior
--result-mode stdout Print full result to stdout, skip artifact files (default)
--result-mode artifact Write artifact files, print summary
--result-mode both Write artifacts and print full result

Use --save-artifacts to keep stdout mode while still writing artifacts.

Path Constraints

Restrict which files agents can access:

mco run \
  --repo . \
  --prompt "Analyze the adapter layer." \
  --providers claude,codex \
  --allow-paths runtime,scripts \
  --target-paths runtime/adapters \
  --enforcement-mode strict

Defaults and Overrides

MCO is zero-config by default. You can also persist defaults in config files:

  • Project config: .mcorc.json in the repo root
  • Global config: ~/.mco/config.json

Merge order: CLI flags > project config > global config > built-in defaults. Nested objects (like policy) are deep-merged.

Key Runtime Flags

Flag Default Description
--providers claude,codex Comma-separated provider list
--stall-timeout 900 Cancel when no output progress for this duration (seconds)
--review-hard-timeout 1800 Hard deadline for review mode; 0 disables
--max-provider-parallelism 0 0 = full parallelism across selected providers
--enforcement-mode strict strict fails closed on unmet permissions
--strict-contract off Enforce strict findings JSON contract (review mode)
--format report Output format: report, markdown-pr, sarif (review-only for last two)
--include-token-usage off Best-effort per-provider and aggregate token usage
--synthesize off Run extra LLM pass for consensus/divergence summary
--synth-provider claude Which provider runs the synthesis pass
--provider-timeouts unset Per-provider stall-timeout overrides (provider=seconds)
--provider-permissions-json unset Provider permission mapping JSON (see below)
--save-artifacts off Write artifacts while keeping stdout result delivery
--task-id auto-generated Stable task identifier for artifact paths
--artifact-base reports/review Base directory for artifact output
--memory off Enable cross-session memory via evermemos-mcp
--space auto Space slug for memory storage (default: inferred from git remote)
--diff off Review only changes vs merge-base with main/master
--staged off Review only staged changes
--unstaged off Review only unstaged working tree changes
--diff-base auto Git ref for branch diff (e.g. origin/main, HEAD~3). Implies --diff
--stream off jsonl for machine-readable events, live for interactive terminal rendering
--transport shim shim (stdout parsing) or acp (Agent Client Protocol JSON-RPC)
--agent unset Temporary custom ACP agent: --agent NAME "command". Works with shim or acp transport
--file unset Read prompt from file path, or - for stdin. Mutually exclusive with --prompt
--quiet off Output only final text, no headers or formatting. Mutually exclusive with --json/--stream
--chain off Run providers sequentially, feeding each output as context to the next
--debate off Run a second challenge round on merged findings
--divide off files or dimensions task division across providers
--perspectives-json unset Per-provider review perspective JSON (e.g. '{"claude":"security","codex":"performance"}')

Default provider permissions:

Provider Key Default
claude permission_mode plan
codex sandbox workspace-write

Override example:

mco review \
  --repo . \
  --prompt "Review for bugs." \
  --providers claude,codex,qwen \
  --save-artifacts \
  --stall-timeout 900 \
  --review-hard-timeout 1800 \
  --max-provider-parallelism 0 \
  --provider-timeouts qwen=900,codex=900

Config File Example

// .mcorc.json
{
  "providers": ["claude", "codex", "gemini"],
  "transport": "acp",
  "quiet": true,
  "policy": {
    "stall_timeout_seconds": 600,
    "enforcement_mode": "best_effort",
    "max_provider_parallelism": 3,
    "chain": false,
    "perspectives": {
      "claude": "Focus on security vulnerabilities and injection attacks",
      "codex": "Focus on performance bottlenecks and resource leaks",
      "gemini": "Focus on code maintainability and design patterns"
    }
  }
}

Run mco review --help for the full flag list.

Custom Agents

Config files are loaded in priority order:

  1. .mco/agents.yaml (project-specific)
  2. .mcorc.yaml (project root)
  3. ~/.mco/agents.yaml (global)

Inspect what MCO sees:

mco agent list
mco agent check my-ollama

Example .mco/agents.yaml:

agents:
  - name: my-acp-agent
    transport: acp
    command: my-agent --acp
    permission_keys: [sandbox]

  - name: my-shim-agent
    transport: shim
    command: my-review-bot --json

  - name: my-ollama
    model: qwen2.5-coder:14b

How it works:

  • transport: acp registers a custom ACP provider
  • transport: shim registers a command-based shim provider
  • model: ... registers an Ollama-backed provider automatically

This means local Ollama models can participate in the same mco review / mco run workflows as Claude, Codex, Gemini, OpenCode, and Qwen.

Exit Codes

Code Meaning
0 Success
2 FAIL / input / config / runtime error
3 INCONCLUSIVE (review mode only, with --strict-contract)

How It Works

You (Tech Lead)
     │
     ▼
  mco review / mco run
     │
     ├─→ Claude Code  ──┐
     ├─→ Codex CLI      │
     ├─→ Gemini CLI     ├─→ Consensus Engine → Debate / Synthesize → Output
     ├─→ OpenCode       │
     └─→ Qwen Code   ───┘
                              │
                    ┌─────────┼─────────┐
                    ▼         ▼         ▼
                  JSON    SARIF    Markdown-PR
               (stdout)  (CI/CD)  (PR comment)

     ↕  (with --memory)
  evermemos-mcp
  ┌─────────────────────────┐
  │ findings  · agent scores│
  │ run history · priors    │
  └─────────────────────────┘

The calling agent (or user) invokes mco with a prompt and a list of providers. MCO fans out to all selected agents in parallel and waits for all to finish.

Each provider runs as an independent subprocess through a uniform adapter contract:

  1. Detect — check binary presence and auth status
  2. Run — spawn CLI process with prompt, capture stdout/stderr
  3. Poll — monitor process + output byte growth for progress detection
  4. Cancel — SIGTERM/SIGKILL on stall timeout or hard deadline
  5. Normalize — extract structured findings from raw output

Execution model is wait-all: one provider's timeout or failure never stops others.

Retry and Resilience

  • Transient errors (timeout, rate-limit, network) are retried automatically with exponential backoff (default: 1 retry).
  • A single provider failure never blocks other providers.
  • Every invocation executes providers and returns fresh output (no result-cache replay).

Running Inside Claude Code

MCO automatically strips the CLAUDECODE environment variable before spawning provider subprocesses. You can safely run mco from within a Claude Code session.

Artifacts

When artifact writing is enabled (--save-artifacts or --result-mode artifact/both), MCO writes:

reports/review/<task_id>/
  summary.md          # Human-readable summary
  decision.md         # PASS / FAIL / ESCALATE / PARTIAL
  findings.json       # Aggregated normalized findings (review mode)
  run.json            # Machine-readable execution metadata
  providers/          # Per-provider result JSON
  raw/                # Raw stdout/stderr logs

Cross-Session Memory (Powered by evermemos-mcp)

MCO integrates with evermemos-mcp to give your agent team persistent memory across sessions. Add --memory once and MCO starts accumulating institutional knowledge: which findings were real, which agents are reliable for which task types, and what has already been fixed.

Fully opt-in — without --memory, MCO behaves exactly as before.

# Install the optional dependency
pip install mco[memory]

# Run with memory enabled
mco review \
  --repo . \
  --prompt "Review for security issues." \
  --providers claude,codex,gemini \
  --memory

What memory adds:

Phase What happens
Pre-run Prior findings injected into prompt with confidence grades [HIGH]/[MEDIUM]/[LOW]
Pre-run Agent weights loaded — more reliable agents get more weight in consensus
Post-run New findings persisted with finding hash for cross-run deduplication
Post-run Agent scores updated (cross-validation: agents that agree get higher reliability)
Post-run Passively fixed findings auto-confirmed (disappeared + file changed = fixed)

Finding lifecycle:

open → passive_fix_candidate → fixed
            ↓
         (rejected / wontfix / accepted)

A finding that disappears when its file was changed is marked passive_fix_candidate. If it stays absent a second consecutive run, it's auto-confirmed as fixed — no manual intervention needed.

Agent reliability:

MCO tracks each agent's cross-validation rate per task category (security, performance, logic, architecture, style). Agents that consistently agree with others on real findings build up higher reliability scores. Cold-start blends repo-specific, tech-stack, and global baseline scores until enough runs accumulate.

Memory Subcommands

mco memory status                      # Memory spaces and finding/score counts
mco memory agent-stats                 # Per-agent reliability scores
mco memory priors --category security  # Blended agent weight priors for a task type

mco findings list                      # All persisted findings
mco findings list --status open        # Filter by status
mco findings confirm <hash>            # Manually mark a finding as fixed

Storage Design

  • Backend: evermemos-mcp via uvx evermemos-mcp@latest (append-only, MCP stdio protocol)
  • Finding hash: sha256(repo + file_path + category + normalize(title)) — stable across runs, independent of line numbers or severity changes
  • Spaces: coding:<slug>--findings, coding:<slug>--agents, coding:<slug>--context, coding:stacks--<tech>, coding:global--agents
  • Deduplication: client-side latest-wins on read; all writes are appends

Requires EVERMEMOS_API_KEY environment variable. See mco review --help for --space and other memory flags.

MCP Server Mode

MCO can run as an MCP server, allowing AI agents and MCP-compatible clients to call MCO tools programmatically over stdio.

pip install mco[memory]  # includes mcp dependency

Configure in your MCP client:

{
  "mcpServers": {
    "mco": {
      "command": "mco",
      "args": ["serve"]
    }
  }
}

Available tools: mco_review, mco_run, mco_doctor, mco_findings_list, mco_memory_status

All tools return a uniform envelope: {"ok": true, "data": ...} on success, {"ok": false, "error": {"code": "...", "message": "..."}} on failure.

License

MIT — see LICENSE

About

Orchestrate AI coding agents. Any prompt. Any agent. Any IDE. Neutral orchestration layer for Claude Code, Codex CLI, Gemini CLI, OpenCode, Qwen Code — works from Cursor, Trae, Copilot, Windsurf, or plain shell.

Topics

cli orchestration multi-agent gemini developer-tools code-review trae cursor copilot codex ai-agents claude windsurf ai-ide qwen

Resources

Readme

License

MIT license
Activity
Custom properties

Stars

255 stars

Watchers

3 watching

Forks

23 forks
Report repository

Releases 11

v0.8.0 Latest
Mar 17, 2026
+ 10 releases

Packages

 
 
 

Contributors

Languages