Claude Code Orchestrator MCP

GPT-class models are excellent.

But Plus-level quotas are not infinite.

If you spawn many internal subagents directly inside Codex, your best-model quota can disappear fast.

A deep repo audit, a parallel multi-agent review, or one ambitious refactor can burn through the budget you wanted to save for judgment.

That is why this Skill exists.

The mission:

Make Plus feel like Pro.

This Skill turns that constraint into an engineering system:

Let the best model act as the brain.
Let Claude Code plus your CCSwitch models act as hands.
Let Codex stay in control.

In other words:

Codex does not need to do every low-level subtask itself.
Codex plans, routes, supervises, and verifies.
Claude Code executes through external worker models.

This is a miniature cost-management operating system for multi-agent coding.

claude-code-orchestrator-skill is a Codex Skill with a bundled MCP server and CLI.

It lets Codex:

• discover local Claude Code

• read CCSwitch profiles

• find all configured Claude-compatible models

• score models by role

• route agents to the best local model

• launch Claude Code as an external worker

• keep runs read-only by default

• save run metadata and logs

• expose everything through MCP tools

• handle Windows UTF-8 output safely

• write a project CLAUDE.md so Claude Code workers receive stable role/persona instructions

You need:

1. Codex

2. Claude Code

3. CCSwitch

4. Multiple models configured inside CCSwitch

5. Python 3.10+

The Skill is most powerful when CCSwitch has several models with different strengths:

• strong reasoning model

• strong code model

• fast cheap model

• review/security model

• fallback model

Paste this into Codex:

Install the Codex Skill and MCP server from https://github.com/chu459/claude-code-orchestrator-skill. Put the Skill at ~/.codex/skills/claude-code-orchestrator, wire the bundled MCP server into Codex config.toml, run selftest, healthcheck, score-models, and show me the selected multi-agent routing plan. Do not print secrets.

Windows PowerShell:

$tmp = Join-Path $env:TEMP "claude-code-orchestrator-skill.zip"; `
iwr -UseBasicParsing "https://github.com/chu459/claude-code-orchestrator-skill/archive/refs/heads/main.zip" -OutFile $tmp; `
$dir = Join-Path $env:TEMP "claude-code-orchestrator-skill"; `
if (Test-Path $dir) { Remove-Item $dir -Recurse -Force }; `
Expand-Archive $tmp -DestinationPath $dir -Force; `
& (Get-ChildItem $dir -Recurse -Filter install.ps1 | Select-Object -First 1).FullName

macOS / Linux:

tmp="$(mktemp -d)" && \
curl -L "https://github.com/chu459/claude-code-orchestrator-skill/archive/refs/heads/main.zip" -o "$tmp/skill.zip" && \
unzip -q "$tmp/skill.zip" -d "$tmp" && \
bash "$tmp"/claude-code-orchestrator-skill-main/install/install.sh

Add this to Codex config.toml:

[mcp_servers.claude-code-orchestrator]
command = "python"
args = [
  "-c",
  "import os,sys,runpy; home=os.environ.get('CODEX_HOME') or os.path.join(os.environ.get('USERPROFILE') or os.path.expanduser('~'), '.codex'); root=os.environ.get('CC_ORCHESTRATOR_HOME') or os.path.join(home, 'skills', 'claude-code-orchestrator', 'scripts', 'cc-orchestrator'); sys.path.insert(0, root); runpy.run_path(os.path.join(root, 'server.py'), run_name='__main__')"
]

[mcp_servers.claude-code-orchestrator.env]
PYTHONIOENCODING = "utf-8"
PYTHONUTF8 = "1"

export CC_ORCHESTRATOR_HOME="$HOME/.codex/skills/claude-code-orchestrator/scripts/cc-orchestrator"
python "$CC_ORCHESTRATOR_HOME/cc_orchestrator.py" selftest
python "$CC_ORCHESTRATOR_HOME/cc_orchestrator.py" healthcheck
python "$CC_ORCHESTRATOR_HOME/cc_orchestrator.py" score-models

Healthcheck:

python "$CC_ORCHESTRATOR_HOME/cc_orchestrator.py" healthcheck

List CCSwitch profiles:

python "$CC_ORCHESTRATOR_HOME/cc_orchestrator.py" list-profiles

Score local models:

python "$CC_ORCHESTRATOR_HOME/cc_orchestrator.py" score-models

Write strategy reports:

python "$CC_ORCHESTRATOR_HOME/cc_orchestrator.py" write-reports

Write a CLAUDE.md worker persona into a project:

python "$CC_ORCHESTRATOR_HOME/cc_orchestrator.py" write-claude-md --cwd /path/to/project --role implementation

Run a read-only architecture worker:

python "$CC_ORCHESTRATOR_HOME/cc_orchestrator.py" run "Map this repository architecture" --role architecture

Open a visible Claude Code worker window:

python "$CC_ORCHESTRATOR_HOME/cc_orchestrator.py" run-visible "Inspect this repository" --role architecture

Inspect the latest run:

python "$CC_ORCHESTRATOR_HOME/cc_orchestrator.py" last-run

Claude Code can read a project-level CLAUDE.md file.

This is extremely useful for orchestration, because Codex can set the worker's persona before launching it.

The generated CLAUDE.md tells Claude Code:

• Codex is the controller, planner, reviewer, and final decision maker

• Claude Code is an external worker process

• the assigned role, such as architecture, implementation, or review

• safety rules about secrets, destructive commands, and unrelated changes

• progress-reporting rules for long-running work

Create one:

python "$CC_ORCHESTRATOR_HOME/cc_orchestrator.py" write-claude-md --cwd /path/to/project --role review

If the project already has CLAUDE.md, the command is conservative:

• default: do not overwrite

• --append: append the orchestrator-managed section

• --force: replace after writing a timestamped backup

Through MCP, Codex can call:

cc_write_claude_md

Recommended flow:

1. Codex plans the work
2. Codex writes CLAUDE.md for the selected worker role
3. Codex launches Claude Code through this Skill
4. Claude Code follows the project persona and role rules
5. Codex reviews logs, diffs, and final output

This project is not just “spawn more agents”.

It is:

Brain: best model for judgment
Hands: cheaper/faster worker models for execution
Ledger: every run saved
Manager: Codex controls the flow

That is why it is a cost-management harness.

flowchart TD
  User["User"] --> Codex["Codex Controller"]
  Codex --> Skill["Claude Code Orchestrator Skill"]
  Skill --> MCP["Bundled MCP Server"]
  Skill --> CLI["cc_orchestrator.py CLI"]
  MCP --> Router["Role + Model Router"]
  CLI --> Router
  Router --> CCSwitch["CCSwitch Profiles"]
  CCSwitch --> Models["Qwen / GLM / Claude-compatible Models"]
  Router --> ClaudeMD["Project CLAUDE.md"]
  ClaudeMD --> ClaudeCode["Claude Code Worker Process"]
  Router --> ClaudeCode
  ClaudeCode --> Runs["runs/<run_id> logs"]
  Runs --> Codex

The default posture is intentionally conservative:

• read-only planning by default

• permission_mode = plan unless write access is explicitly enabled

• allow_write=true required for scoped implementation work

• no global CCSwitch mutation

• secrets are redacted from tool output and persisted logs

• UTF-8-safe output on Windows

• timeout output is preserved when Python exposes partial stdout/stderr

• existing CLAUDE.md files are not overwritten unless --append or --force is used

What works today:

1. use run-visible to watch Claude Code in a real terminal window

2. use last-run to inspect the latest run metadata and tails

3. tail the saved stdout/stderr files

Windows:

Get-Content "$env:CC_ORCHESTRATOR_HOME\runs\<run_id>\stdout.txt" -Wait

macOS / Linux:

tail -f "$CC_ORCHESTRATOR_HOME/runs/<run_id>/stdout.txt"

The next serious upgrade is an event stream:

events.jsonl
cc_watch_runs
cc_run_status
terminal dashboard
Codex live polling

Full design notes:

docs/realtime-progress.md

The goal is intentionally ambitious:

Become one of the world's top multi-agent collaboration harnesses: strong models as the brain, cheaper models as hands, Codex as controller, and MCP as the nervous system.

This is not about spectacle.

It is about bringing model cost, context cost, worker cost, and human attention cost into one auditable engineering loop.

• Codex Skill

• Bundled MCP Server

• CCSwitch profile discovery

• Local model scoring

• Role-based model routing

• Claude Code subprocess launching

• Visible Claude Code window

• UTF-8 safe Windows output

• Run logs and last-run

• CLAUDE.md worker persona writer

• Live event stream

• Terminal dashboard

• Web dashboard

• Cost budget policy

• Parallel run coordinator

• Agent result voting

• Automatic cross-review

MIT.

Not affiliated with OpenAI, Anthropic, Claude, Claude Code, or CCSwitch.