You're working on a task that's too big for a single AI agent call:
"Add JWT auth to this Express app — with tests, middleware, and docs"
"Refactor the payment module — 15 files across 3 packages"
"Fix all failing tests after the database migration"
A single claude or codex session gets lost in context, misses dependencies, or produces inconsistent code across files. You end up manually coordinating multiple runs, checking outputs, and stitching results together.
The Solution
Master Orchestrator turns one natural-language goal into a directed acyclic graph (DAG) of tasks, then executes them with the best AI agent for each phase:
mo do "Add JWT authentication to the Express app with middleware, routes, tests, and API docs"
It automatically:
your goal into dependent sub-tasks (Claude excels here)
First-time install walkthrough for Claude Code, Codex CLI, and ChatGPT.
Decomposes
Routes each task to the optimal provider (Claude for reasoning, Codex for execution)
Executes independent tasks in parallel (up to 150 concurrent)
Reviews outputs with cross-agent verification
Retries failures with exponential backoff and error classification
Converges on a verified, consistent result
Why Master Orchestrator?
| Scenario | Single Agent | Master Orchestrator |
|----------|-------------|-------------------|
| 5-file refactor | Context overflow, inconsistent edits | DAG decomposition, parallel execution |
| Bulk fixes (100+ files) | Sequential, slow, no retry | Simple mode: 16 parallel workers, auto-retry |
| Complex feature | Manual coordination of multiple runs | Automatic phase routing, convergence detection |
| Mixed tasks | Same model for reasoning and coding | Claude for planning, Codex for execution |
Quick Start
Install
git clone https://github.com/amber132/Master-Orchestrator.git
cd Master-Orchestrator
pip install -e ".[dev]"
Requires Python 3.11+ and at least one of claude or codex on your PATH.
Your First Orchestrated Task
# Let the orchestrator auto-route providers
mo do "Add input validation to all POST endpoints in src/routes/"
# Force a specific provider
mo do --provider codex "Generate unit tests for the UserService class"
# Mix providers by phase — Claude plans, Codex executes, Claude reviews
mo do \
--phase-provider decompose=claude \
--phase-provider execute=codex \
--phase-provider review=claude \
"Refactor the payment module to support multiple currencies"
Bulk Operations with Simple Mode
For hundreds of independent work items (linting, formatting, repetitive edits):
# Scan and execute from a task manifest
mo simple run --manifest tasks.jsonl
# Resume after interruption
mo simple resume
# Retry only failures
mo simple retry
Simple mode runs up to 16 parallel workers with automatic retry, syntax validation, and crash recovery.
Each phase of the pipeline can use a different AI agent:
| Phase | Default Provider | Why |
|-------|-----------------|-----|
| decompose | Claude | Better at planning and dependency analysis |
| execute | Codex | Faster for code generation |
| review | Claude | Better at reasoning about correctness |
| discover | Claude | Better at research and exploration |
| simple | Codex | Optimized for high-throughput bulk tasks |
Override at any level:
# Global override
mo do --provider claude "..."
# Per-phase override
mo do --phase-provider execute=codex --phase-provider review=claude "..."
# Config file (config.toml)
[routing.phase_defaults]
execute = "codex"
review = "claude"
Error Recovery
The orchestrator classifies errors and applies appropriate strategies:
Rate limits → exponential backoff with jitter
Context overflow → automatic context compaction and retry
Transient failures → up to 10 retries with 30s base backoff
Provider down → fallback to alternate provider (auto mode only)
Task failure → propagate to dependents, skip unreachable tasks
Convergence Detection
The system monitors for:
Plateaus — no progress across iterations → escalate or pivot strategy
Deterioration — quality declining → rollback to last good state
Regression — previously passing tests failing → halt and alert
The agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.
Claude Code is an agentic coding tool that lives in your terminal, understands your codebase, and helps you code faster by executing routine tasks, explaining complex code, and handling git workflows - all through natural language commands.
