Codex Orchestrator
Delegate tasks to OpenAI Codex agents via tmux sessions. Designed for Claude Code orchestration.
Spawn parallel coding agents, monitor their progress, send follow-up messages mid-task, and capture results - all from Claude Code or the command line.
Installation
As a Claude Code Plugin (Recommended)
Step 1: Add the marketplace:
/plugin marketplace add kingbootoshi/codex-orchestrator
Step 2: Install the plugin:
/plugin install codex-orchestrator
Step 3: Restart Claude Code (may be required for the skill to load)
Step 4: Install the CLI and dependencies:
/codex-orchestrator init
Or say "set up codex orchestrator" and Claude will walk you through it.
Step 5: Use it - just ask Claude to do things. The skill activates automatically for coding tasks.
Manual / CLI-Only Install
If you just want the codex-agent CLI without the Claude Code plugin:
# Prerequisites
brew install tmux # macOS (or apt/pacman/dnf for Linux)
npm install -g @openai/codex # OpenAI Codex CLI
codex --login # Authenticate with OpenAI
# Install
git clone https://github.com/kingbootoshi/codex-orchestrator.git ~/.codex-orchestrator
cd ~/.codex-orchestrator && bun install
# Add to PATH (add this line to ~/.bashrc or ~/.zshrc)
export PATH="$HOME/.codex-orchestrator/bin:$PATH"
# Verify
codex-agent health
Or use the automated installer:
bash <(curl -fsSL https://raw.githubusercontent.com/kingbootoshi/codex-orchestrator/main/plugins/codex-orchestrator/scripts/install.sh)
Requirements
| Dependency | Purpose | Install |
|---|---|---|
| tmux | Terminal multiplexer - agents run in tmux sessions | brew install tmux |
| Bun | JavaScript runtime - runs the CLI | curl -fsSL https://bun.sh/install | bash |
| Codex CLI | OpenAI's coding agent - the thing being orchestrated | npm install -g @openai/codex |
| OpenAI account | API access for Codex agents | codex --login |
Platform support: macOS and Linux. Windows users should use WSL.
Why?
When you're working with Claude Code and need parallel execution, investigation tasks, or long-running operations - spawn Codex agents in the background. They run in tmux sessions so you can:
- Watch live - Attach to any session and see exactly what the agent is doing
- Talk back - Send follow-up messages mid-task to redirect or add context
- Run in parallel - Spawn multiple agents investigating different parts of a codebase
- Capture results - Grab output programmatically when agents finish
Claude handles the strategic thinking (planning, synthesis, communication). Codex handles the deep coding work (research, implementation, review, testing). Together they cover both the orchestration and execution layers.
Codebase Map (Recommended)
The --map flag injects docs/CODEBASE_MAP.md into every agent's prompt, giving them instant understanding of your entire codebase: file purposes, module boundaries, data flows, dependencies, and navigation guides.
Without a map, agents waste time exploring and guessing at structure. With a map, they know exactly where things are and start working immediately.
The map is generated by Cartographer, a companion Claude Code plugin:
/plugin marketplace add kingbootoshi/cartographer
/plugin install cartographer
/cartographer
This creates docs/CODEBASE_MAP.md. After that, every codex-agent start ... --map command gives agents full architectural context. Generate a codebase map before using codex-orchestrator on a new project - it's the difference between agents that fumble around and agents that execute with precision.
Quick Start
# Start an agent
codex-agent start "Review this codebase for security vulnerabilities" --map
codex-agent start "Refactor auth module" --wait --notify-on-complete 'printf "\033[0;32mCodex agent done\033[0m\n"'
# Check status with structured JSON
codex-agent jobs --json
# See what it's doing
codex-agent capture <jobId>
# Redirect the agent mid-task
codex-agent send <jobId> "Focus on the authentication module instead"