Delegate tasks to OpenAI Codex agents via tmux sessions. Designed for Claude Code orchestration.

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

• Bun - JavaScript runtime
• tmux - Terminal multiplexer
• Codex CLI - OpenAI's coding agent

# macOS
brew install tmux
npm install -g @openai/codex

# Verify
codex --version
tmux -V

git clone https://github.com/kingbootoshi/codex-orchestrator.git
cd codex-orchestrator
bun install

# Add to PATH (optional)
sudo ln -sf "$(pwd)/bin/codex-agent" /usr/local/bin/codex-agent

# Start an agent
codex-agent start "Review this codebase for security vulnerabilities" --map

# 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"

Get structured job data with jobs --json:

{
  "id": "8abfab85",
  "status": "completed",
  "elapsed_ms": 14897,
  "tokens": {
    "input": 36581,
    "output": 282,
    "context_window": 258400,
    "context_used_pct": 14.16
  },
  "files_modified": ["src/auth.ts", "src/types.ts"],
  "summary": "Implemented the authentication flow..."
}

Fields:

• tokens: Input/output tokens and context window usage
• files_modified: Files changed via apply_patch
• summary: Agent's final response (truncated to 500 chars)

# Spawn multiple agents to investigate different areas
codex-agent start "Audit authentication flow" -r high --map -s read-only
codex-agent start "Review database queries for N+1 issues" -r high --map -s read-only
codex-agent start "Check for XSS vulnerabilities in templates" -r high --map -s read-only

# Check on all of them with structured output
codex-agent jobs --json

# Results include tokens used, files modified, and summary

# Agent going down wrong path? Send a message to redirect
codex-agent send abc123 "Stop - focus on the auth module instead"

# Agent needs info? Send it
codex-agent send abc123 "The dependency is installed. Continue with typecheck."

# Attach for direct interaction if needed
tmux attach -t codex-agent-abc123
# (Ctrl+B, D to detach)

# Include specific files
codex-agent start "Review these files for bugs" -f "src/auth/**/*.ts" -f "src/api/**/*.ts"

# Include codebase map for orientation
codex-agent start "Understand the architecture" --map -r high

1. You run codex-agent start "task"
2. It creates a detached tmux session
3. It launches the Codex CLI inside that session
4. It sends your prompt to Codex
5. It returns immediately with the job ID
6. Codex works in the background
7. You check with jobs --json, capture, output, or attach
8. You redirect with send if the agent needs course correction

All session output is logged via the script command, so you can retrieve results even after the session ends.

Session metadata is parsed from Codex's JSONL files (~/.codex/sessions/) to extract tokens, file modifications, and summaries.

Jobs are stored in ~/.codex-agent/jobs/:

~/.codex-agent/jobs/
├── <jobId>.json    # Job metadata
├── <jobId>.prompt  # Original prompt
└── <jobId>.log     # Full terminal output

• Use codex-agent send to redirect agents - don't kill and respawn
• Use jobs --json to get structured data (tokens, files, summary) in one call
• Use --strip-ansi when capturing output programmatically
• Use -r xhigh for complex investigation tasks that need deep reasoning
• Use --map to give agents codebase context (requires docs/CODEBASE_MAP.md)
• Use -s read-only for research tasks that shouldn't modify files
• Kill stuck jobs with codex-agent kill <id> only as a last resort

MIT