Codex Orchestrator — Development agent for Claude Code

Codex Orchestrator

CLI tool for delegating tasks to GPT Codex agents via tmux sessions. Designed for Claude Code orchestration with bidirectional communication.

**Stack**: TypeScript, Bun, tmux, OpenAI Codex CLI

**Structure**: Shell wrapper -> CLI entry point -> Job management -> tmux sessions

For detailed architecture, see [docs/CODEBASE_MAP.md](docs/CODEBASE_MAP.md).

Development

# Run directly
bun run src/cli.ts --help

# Or via shell wrapper
./bin/codex-agent --help

# Health check
bun run src/cli.ts health

Key Files

File	Purpose
src/cli.ts	CLI commands and argument parsing
src/jobs.ts	Job lifecycle and persistence
src/tmux.ts	tmux session management
src/config.ts	Configuration constants
src/files.ts	File loading for context injection
src/session-parser.ts	Parse Codex session files for metadata
plugins/	Claude Code plugin (marketplace structure)

Plugin Structure

This repo doubles as a Claude Code plugin marketplace:

.claude-plugin/marketplace.json     # marketplace registry
plugins/codex-orchestrator/         # the plugin
  .claude-plugin/plugin.json        # plugin metadata
  skills/codex-orchestrator/        # the orchestration skill
    SKILL.md                        # skill instructions
  scripts/install.sh                # dependency installer

Dependencies

• Runtime: Bun, tmux, codex CLI
• NPM: glob (file matching)

Notes

• Jobs stored in ~/.codex-agent/jobs/
• Uses script command for output logging
• Completion detected via marker string in output
• Bun is the TypeScript runtime - never use npm/yarn/pnpm for running

Claude Orchestration Pattern (Persisted)

• Use codex-agent start "" without --wait for background orchestration.
• Track job IDs immediately.
• Use codex-agent status to check running/completed state.
• Use codex-agent capture [n] for incremental tails while running.
• Use codex-agent output for final transcript after completion.