Claude Code Orchestrator

Claude Code Orchestrator

Use this skill when Codex should control Claude Code through the bundled orchestrator. Prefer $env:CC_ORCHESTRATOR_HOME when set; otherwise use the installed skill's scripts/cc-orchestrator directory or the current workspace's tools/cc-orchestrator.

Operating Model

Codex remains the controller. Claude Code is an external worker launched through the orchestrator. Do not treat Claude Code output as final until Codex has reviewed logs, diffs, and verification results.

Codex owns planning, write-scope decisions, final review, and final response. Claude Code agents only provide role-specific analysis or scoped edits when Codex explicitly enables write access.

Default routing:

• Discover CCSwitch from $env:CCSWITCH_HOME, $env:USERPROFILE\.cc-switch, or the current user home.
• Discover Claude Code from $env:CLAUDE_CODE_BIN, where claude, and common Claude Code install paths.
• Score every Claude model found in CCSwitch, then choose the best local model for each agent role.

The orchestrator reads CCSwitch profiles in read-only mode and injects provider env vars only into the launched Claude Code process. It should not rewrite CCSwitch global state.

Reference Files

When deciding how to supervise Claude Code workers, read references/codex-controller-playbook.md.

When assigning repeatable worker tasks, read references/prompt-pack/README.md, then open only the needed prompt template.

The runtime role configuration still lives in scripts/cc-orchestrator/config/agents.json. The prompt pack is controller guidance, not the only routing source.

Worker Roles

Supported primary roles:

• requirements: clarify needs, gaps, plans, constraints, and acceptance criteria.
• development: implement scoped code changes when write access is granted.
• testing: design or run focused checks, edge cases, and failure-mode tests.
• review: review code quality, bugs, maintainability, and release blockers.
• performance: inspect slow paths, resource use, blocking IO, and measurable optimizations.
• compatibility: check OS, shell, dependency, version, and install portability.
• documentation: improve examples, onboarding, FAQ, and troubleshooting.
• automation: design CI/CD, tests, packaging, release, and repeatable scripts.
• security: audit secrets, permissions, injection, privacy, and destructive paths.
• ops: check deployment, logs, observability, release safety, and rollback.

Legacy/support roles still work: architecture, implementation, and multimodal.

Preferred Commands

If $env:CC_ORCHESTRATOR_HOME is not set, set it to the workspace orchestrator path first:

$workspaceTool = Join-Path (Get-Location) "tools\cc-orchestrator"
$installedSkillTool = Join-Path $env:USERPROFILE ".codex\skills\claude-code-orchestrator\scripts\cc-orchestrator"
$env:CC_ORCHESTRATOR_HOME = if (Test-Path $workspaceTool) { $workspaceTool } else { $installedSkillTool }

Healthcheck:

python "$env:CC_ORCHESTRATOR_HOME\cc_orchestrator.py" healthcheck

Fast self-test for UTF-8 handling and required config files:

python "$env:CC_ORCHESTRATOR_HOME\cc_orchestrator.py" selftest

Initialize and inspect the managed agent workspace:

python "$env:CC_ORCHESTRATOR_HOME\cc_orchestrator.py" init-workspace --cwd "PROJECT_PATH"
python "$env:CC_ORCHESTRATOR_HOME\cc_orchestrator.py" workspace-status --cwd "PROJECT_PATH"
python "$env:CC_ORCHESTRATOR_HOME\cc_orchestrator.py" folder-policy --cwd "PROJECT_PATH" --apply

Move and maintain old agent artifacts safely:

python "$env:CC_ORCHESTRATOR_HOME\cc_orchestrator.py" migrate-data --cwd "PROJECT_PATH"
python "$env:CC_ORCHESTRATOR_HOME\cc_orchestrator.py" migrate-data --cwd "PROJECT_PATH" --apply
python "$env:CC_ORCHESTRATOR_HOME\cc_orchestrator.py" clean-workspace --cwd "PROJECT_PATH"
python "$env:CC_ORCHESTRATOR_HOME\cc_orchestrator.py" archive-runs --cwd "PROJECT_PATH" --older-than-days 30
python "$env:CC_ORCHESTRATOR_HOME\cc_orchestrator.py" repair-mcp-paths --cwd "PROJECT_PATH" --create --apply

clean-workspace, migrate-data, archive-runs, and repair-mcp-paths are preview-first unless --apply is passed. They manage only agent-generated artifacts under .agent-workspace/claude-code-orchestrator plus explicitly requested CLAUDE.md or .mcp.json updates.

List profiles:

python "$env:CC_ORCHESTRATOR_HOME\cc_orchestrator.py" list-profiles

Score local models:

python "$env:CC_ORCHESTRATOR_HOME\cc_orchestrator.py" score-models

Write the portable auto-routing policy:

python "$env:CC_ORCHESTRATOR_HOME\cc_orchestrator.py" write-auto-policy

Generate score and strategy reports:

python "$env:CC_ORCHESTRATOR_HOME\cc_orchestrator.py" write-reports

Create or update a project CLAUDE.md for Claude Code sub-agents:

python "$env:CC_ORCHESTRATOR_HOME\cc_orchestrator.py" write-claude-md --cwd "PROJECT_PATH" --role development

If a project already has CLAUDE.md, preserve it by default. Use --append to add the managed orchestrator section, or --force to replace after writing a timestamped backup.

Pick a route without running Claude Code:

python "$env:CC_ORCHESTRATOR_HOME\cc_orchestrator.py" pick --role performance --task-type performance_review

Run Claude Code non-interactively:

python "$env:CC_ORCHESTRATOR_HOME\cc_orchestrator.py" run "TASK" --role development

Run Claude Code as a streaming background worker:

python "$env:CC_ORCHESTRATOR_HOME\cc_orchestrator.py" run-streaming "TASK" --role review

Poll a streaming run:

python "$env:CC_ORCHESTRATOR_HOME\cc_orchestrator.py" poll-run --run-id RUN_ID --mode controller
python "$env:CC_ORCHESTRATOR_HOME\cc_orchestrator.py" summarize-run --run-id RUN_ID
python "$env:CC_ORCHESTRATOR_HOME\cc_orchestrator.py" compact-events --run-id RUN_ID

List active streaming workers:

python "$env:CC_ORCHESTRATOR_HOME\cc_orchestrator.py" run-status

Stop a runaway worker:

python "$env:CC_ORCHESTRATOR_HOME\cc_orchestrator.py" stop-run --run-id RUN_ID --force

Spawn a role team:

python "$env:CC_ORCHESTRATOR_HOME\cc_orchestrator.py" spawn-role-team "TASK" --roles requirements,architecture,security,testing

Collect and cross-review team output:

python "$env:CC_ORCHESTRATOR_HOME\cc_orchestrator.py" collect-team-results --team-id TEAM_ID
python "$env:CC_ORCHESTRATOR_HOME\cc_orchestrator.py" cross-review --run-id RUN_ID --run-id RUN_ID

Preflight writes and inspect risk:

python "$env:CC_ORCHESTRATOR_HOME\cc_orchestrator.py" preflight-write-scope --cwd PROJECT_PATH --allow src --deny .env --max-diff-lines 800
python "$env:CC_ORCHESTRATOR_HOME\cc_orchestrator.py" check-write-scope --cwd PROJECT_PATH
python "$env:CC_ORCHESTRATOR_HOME\cc_orchestrator.py" diff-summary --cwd PROJECT_PATH
python "$env:CC_ORCHESTRATOR_HOME\cc_orchestrator.py" secret-scan-run --run-id RUN_ID
python "$env:CC_ORCHESTRATOR_HOME\cc_orchestrator.py" verify-run --run-id RUN_ID --test-command "pytest"

Benchmark, calibrate, and guard cost:

python "$env:CC_ORCHESTRATOR_HOME\cc_orchestrator.py" benchmark-model --profile PROFILE --execute
python "$env:CC_ORCHESTRATOR_HOME\cc_orchestrator.py" benchmark-suite --profile PROFILE
python "$env:CC_ORCHESTRATOR_HOME\cc_orchestrator.py" calibrate-policy --preference coding=glm-5 --preference multimodal=qwen3.7-plus
python "$env:CC_ORCHESTRATOR_HOME\cc_orchestrator.py" cost-guard --max-concurrent 4 --max-timeout-seconds 1200 --apply
python "$env:CC_ORCHESTRATOR_HOME\cc_orchestrator.py" usage-summary --write-report

Generate operator artifacts:

python "$env:CC_ORCHESTRATOR_HOME\cc_orchestrator.py" queue-submit "TASK" --role review --priority 100
python "$env:CC_ORCHESTRATOR_HOME\cc_orchestrator.py" queue-tick --max-concurrent 3
python "$env:CC_ORCHESTRATOR_HOME\cc_orchestrator.py" queue-status
python "$env:CC_ORCHESTRATOR_HOME\cc_orchestrator.py" model-registry --refresh
python "$env:CC_ORCHESTRATOR_HOME\cc_orchestrator.py" local-policy --show
python "$env:CC_ORCHESTRATOR_HOME\cc_orchestrator.py" score-worker --run-id RUN_ID
python "$env:CC_ORCHESTRATOR_HOME\cc_orchestrator.py" render-prompt --template bugfix --task "TASK"
python "$env:CC_ORCHESTRATOR_HOME\cc_orchestrator.py" upgrade-check --apply
python "$env:CC_ORCHESTRATOR_HOME\cc_orchestrator.py" mock-stream-test
python "$env:CC_ORCHESTRATOR_HOME\cc_orchestrator.py" dashboard
python "$env:CC_ORCHESTRATOR_HOME\cc_orchestrator.py" open-run-folder --run-id RUN_ID
python "$env:CC_ORCHESTRATOR_HOME\cc_orchestrator.py" export-report --run-id RUN_ID

For long multi-agent work, split prompts into short role-specific tasks and set a clear timeout. If a run times out, inspect the saved run folder instead of rerunning blindly:

python "$env:CC_ORCHESTRATOR_HOME\cc_orchestrator.py" last-run

Open a visible Claude Code window:

python "$env:CC_ORCHESTRATOR_HOME\cc_orchestrator.py" run-visible "TASK" --role review

Inspect last run:

python "$env:CC_ORCHESTRATOR_HOME\cc_orchestrator.py" last-run

Inspect diff after write-enabled work:

python "$env:CC_ORCHESTRATOR_HOME\cc_orchestrator.py" diff --cwd "PROJECT_PATH"

Safety Rules

• Default to read-only/plan mode.
• Use --allow-write only for scoped implementation tasks after Codex has identified the write set.
• Never print or persist raw API keys. The orchestrator redacts secrets, but still avoid requesting secrets in prompts.
• After any write-enabled Claude Code run, inspect diffs and run verification before reporting success.
• After any write-enabled run, call check-write-scope or verify-run. If write_scope.status=blocked, do not accept the run; inspect the rollback recommendation.
• If the user wants to watch Claude Code work, use run-visible.
• Windows Chinese output is handled with UTF-8 stdio and child-process UTF-8 env. If a host still renders text strangely, rely on the UTF-8 files under .agent-workspace/claude-code-orchestrator/runs/<run_id>/.
• Timeout output is preserved when the subprocess exposes partial stdout/stderr; use last-run to recover the tails.
• For live control, prefer run-streaming: it uses Claude Code stream-json, writes events.ndjson, and enables poll-run, run-status, and stop-run.
• For noisy or uncertain workers, set output budgets with --max-output-bytes, --max-events-bytes, --kill-on-excessive-output, or --final-only.
• Treat spawn-role-team as transactional: if capacity is blocked or partial launch rollback occurs, inspect runs, rollback, and the team manifest before continuing.
• send-instruction preserves the previous profile/model by default. Reroute only when Codex intentionally wants a new route.
• For controller polling, prefer poll-run --mode controller. Raw events.ndjson stays on disk; Codex should usually read compact controller artifacts first.
• Use controller-report / pressure-report after multi-agent or pressure runs to export acceptance evidence.
• Use decision-review before high-impact accept, merge, or release decisions when evidence is thin or risk is nontrivial.
• When Claude Code needs a stable persona, project rules, or role-specific worker behavior, write CLAUDE.md first with write-claude-md or MCP tool cc_write_claude_md, then run the sub-agent from that project cwd.
• Before heavy multi-agent work in a project, run init-workspace or MCP cc_init_workspace. Keep agent logs, reports, dashboards, archives, rollback notes, templates, policies, and temp files under .agent-workspace/claude-code-orchestrator.
• Use folder-policy or MCP cc_folder_policy to make the boundary explicit: manage agent-generated artifacts only; do not clean, archive, or migrate project source files.

Four-Phase Workflow

For the user's multi-agent workflow:

1. Codex plans the write scope and asks role workers for focused input.
2. Run or plan requirements, development, testing, review, performance, compatibility, documentation, automation, security, and ops roles as needed.
3. Cross-review conflicts before enabling any scoped write role.
4. Codex reviews logs, diffs, and verification, then gives the final answer.

Use:

python "$env:CC_ORCHESTRATOR_HOME\cc_orchestrator.py" workflow-plan "TASK"

before launching a full workflow.

MCP Parameter Notes

Use the same role names through MCP:

• cc_pick_profile, cc_run_agent, cc_run_streaming_agent, cc_run_visible_agent, and cc_write_claude_md accept role.
• cc_run_streaming_agent starts a background Claude Code worker and writes events.ndjson.
• cc_run_streaming_agent supports hard output/event budgets and final-only mode.
• cc_poll_run defaults to controller mode: status, compact progress, risk flags, changed files, timeline, and attention signals. Use raw mode only when debugging.
• cc_compact_events returns compact events plus deduplicated tool-call summaries.
• cc_poll_run and cc_summarize_run write progress_summary.json, latest_decision.md, risk_flags.json, changed_files.json, tool_timeline.md, and rolling checkpoints/checkpoint-###.md.
• cc_summarize_run returns the latest controller summary for one run.
• cc_stop_run terminates a specific run id.
• cc_run_status lists active workers or returns one run's status.
• cc_send_instruction stops and restarts a non-interactive run with recovered context and a new instruction.
• cc_send_instruction preserves route by default and reports route drift when rerouted.
• cc_spawn_role_team starts multiple role workers transactionally and writes a team manifest.
• cc_collect_team_results summarizes team outputs and marks repeated agreements plus explicit conflicts/risks.
• cc_cross_review launches second-round reviewer workers over previous outputs.
• cc_preflight_write_scope writes allowed/denied paths and max diff rules before write-enabled work.
• cc_check_write_scope checks whether run output crossed the write-scope boundaries and blocks acceptance on violations.
• cc_diff_summary summarizes changed files, line counts, risk markers, and test need.
• cc_secret_scan_run scans run logs/events/diff for leaked credentials.
• cc_rollback_run conservatively rolls back when a clean pre-run git snapshot proves it is safe.
• cc_verify_run runs diff summary, write-scope check, secret scan, optional tests, and writes a report.
• cc_benchmark_model can run a small real benchmark task when execute=true.
• cc_benchmark_suite can run or plan fixed code/review/security/context/multimodal benchmark tasks.
• cc_model_registry refreshes the local model capability database from CCSwitch, benchmark history, and worker quality history.
• cc_calibrate_policy persists local model preference notes.
• cc_local_policy reads or writes user-owned local routing overrides that upgrades must preserve.
• cc_score_worker grades one worker run and records model quality history.
• cc_prompt_pack lists or renders reusable worker prompt templates.
• cc_cost_guard stores max concurrency and timeout guardrails.
• cc_usage_summary estimates daily tokens, duration, failures, and per-model usage from logs.
• cc_queue_submit, cc_queue_tick, cc_queue_status, and cc_queue_cancel provide priority queue scheduling with queued, running, done, failed, timed_out, and cancelled states.
• cc_upgrade_check records version state while preserving local calibration/cost files.
• cc_mock_stream_test uses a fake Claude stream to validate events.ndjson, polling, status, and stop without spending model quota.
• cc_init_workspace initializes .agent-workspace, run/report/dashboard/archive/rollback/log/tmp/template/policy dirs, and optionally CLAUDE.md.
• cc_workspace_status shows the exact paths where Codex and Claude Code artifacts will be written.
• cc_migrate_data previews or moves legacy runs, reports, and dashboard into the managed workspace.
• cc_clean_workspace cleans tmp files, non-scaffold empty dirs, and expired run folders; it is dry-run by default.
• cc_archive_runs zips selected or old run folders into archives/.
• cc_repair_mcp_paths repairs .mcp.json so MCP uses the managed workspace paths.
• cc_folder_policy returns or writes the policy that limits folder management to agent-generated artifacts.
• cc_dashboard generates a local HTML worker dashboard.
• cc_open_run_folder opens or returns a run log directory.
• cc_export_report writes a Markdown report for a run or team.
• cc_controller_report and cc_pressure_report export controller acceptance and pressure-test reports.
• cc_decision_review returns supervisor-style approve/revise/block guidance for Codex controller decisions.
• role supports requirements, development, testing, review, performance, compatibility, documentation, automation, security, supervisor, ops, plus architecture, implementation, and multimodal.
• task_type supports simple, normal, complex_code, development, review, security_review, supervisor, performance_review, compatibility_review, documentation, automation, architecture, multimodal, and ops.
• cc_workflow_plan returns controller: codex, worker_roles, and one route per configured role.
• cc_score_models returns role_scores for all configured roles.
• cc_write_claude_md embeds the selected role prompt and states that Codex is the controller.