codex-orchestrator

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"

Commands