codex-orchestrator
Delegate tasks to OpenAI Codex agents via tmux sessions. Designed for Claude Code orchestration.
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Badge for your README
Markdown
[](/listings/kingbootoshi--codex-orchestrator)HTML
<a href="/listings/kingbootoshi--codex-orchestrator"><img src="/api/listings/kingbootoshi--codex-orchestrator/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
These steps run a script from the network that findsafeskills does not scan.
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](https://github.com/tmux/tmux) | Terminal multiplexer - agents run in tmux sessions | `brew install tmux` | | [Bun](https://bun.sh) | JavaScript runtime - runs the CLI | `curl -fsSL https://bun.sh/install \| bash` | | [Codex CLI](https://github.com/openai/codex) | 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.
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
.claude-plugin/marketplace.json · Manifest · 21 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
- {
- "name": "codex-orchestrator-marketplace",
- "owner": {
- "name": "Bootoshi",
- "url": "https://github.com/kingbootoshi"
- },
- "metadata": {
- "description": "Delegate tasks to OpenAI Codex agents via tmux sessions. Designed for Claude Code orchestration.",
- "version": "1.0.0"
- },
- "plugins": [
- {
- "name": "codex-orchestrator",
- "source": "./plugins/codex-orchestrator",
- "description": "Orchestrate OpenAI Codex agents from Claude Code. Spawn parallel agents, monitor progress, send follow-up messages, and capture results - all through tmux sessions.",
- "version": "1.0.0",
- "category": "developer tools",
- "keywords": ["codex", "orchestration", "agents", "tmux", "parallel", "delegation"]
- }
- ]
- }
README.md · README · 264 lines · 1 finding marked
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
- # Codex Orchestrator
- <p align="center">
- <img src="codex-agent-hero.jpeg" alt="Claude orchestrating Codex agents" width="600">
- </p>
- 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:
- ```bash
- # 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
- bash <(curl -fsSL https://raw.githubusercontent.com/kingbootoshi/codex-orchestrator/main/plugins/codex-orchestrator/scripts/install.sh)
- Note: Runs a downloaded script through process substitution (bash <(curl …))
- Line 63 on GitHub
- ```
- ### Requirements
- | Dependency | Purpose | Install |
- |-----------|---------|---------|
- | [tmux](https://github.com/tmux/tmux) | Terminal multiplexer - agents run in tmux sessions | `brew install tmux` |
- | [Bun](https://bun.sh) | JavaScript runtime - runs the CLI | `curl -fsSL https://bun.sh/install \| bash` |
- | [Codex CLI](https://github.com/openai/codex) | 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](https://github.com/kingbootoshi/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
- ```bash
- # 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
- | Command | Description |
- |---------|-------------|
- | `start <prompt>` | Start a new agent with the given prompt |
- | `status <id>` | Check job status and details |
- | `send <id> <msg>` | Send a message to redirect a running agent |
- | `capture <id> [n]` | Get last n lines of output (default: 50) |
- | `output <id>` | Get full session output |
- | `attach <id>` | Print tmux attach command |
- | `watch <id>` | Stream output updates |
- | `jobs` | List all jobs |
- | `jobs --json` | List jobs with structured metadata (tokens, files, summary) |
- | `sessions` | List active tmux sessions |
- | `kill <id>` | Terminate a running job (last resort) |
- | `clean` | Remove jobs older than 7 days |
- | `health` | Check tmux and codex availability |
- ## Options
- | Option | Description |
- |--------|-------------|
- | `-r, --reasoning <level>` | Reasoning effort: `low`, `medium`, `high`, `xhigh` |
- | `-m, --model <model>` | Model name (default: gpt-5.4) |
- | `-w, --wait` | Wait for completion and emit a ping when done |
- | `--notify-on-complete <cmd>` | Shell command to run when the job completes |
- | `-s, --sandbox <mode>` | `read-only`, `workspace-write`, `danger-full-access` |
- | `-f, --file <glob>` | Include files matching glob (repeatable) |
- | `-d, --dir <path>` | Working directory |
- | `--map` | Include codebase map (docs/CODEBASE_MAP.md) |
- | `--strip-ansi` | Remove ANSI control codes and Codex TUI noise from output |
- | `--clean` | Alias for `--strip-ansi` |
- | `--json` | Output JSON (jobs command only) |
- | `--dry-run` | Preview prompt without executing |
- ## Jobs JSON Output
- Get structured job data with `jobs --json`:
- ```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..."
- }
- ```
- ## Examples
- ### Parallel Investigation
- ```bash
- # 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
- codex-agent jobs --json
- ```
- ### Redirecting an Agent
- ```bash
- # Agent going down wrong path? Redirect it
- 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
- tmux attach -t codex-agent-abc123
- # (Ctrl+B, D to detach)
- ```
- ### With File Context
- ```bash
- # Include specific files in the prompt
- 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
- ```
- ## How It Works
- 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 results are available even after the session ends. Session metadata is parsed from Codex's JSONL files (`~/.codex/sessions/`) to extract tokens, file modifications, and summaries.
- ## The Claude Code Plugin
- When installed as a Claude Code plugin, the **codex-orchestrator skill** teaches Claude how to use the CLI automatically. Claude becomes the orchestrator:
- - Breaks your requests into agent-sized tasks
- - Spawns agents with the right flags (read-only for research, workspace-write for implementation)
- - Monitors agent progress
- - Synthesizes findings from multiple agents
- - Course-corrects agents that drift off-task
- This means you can just describe what you want, and Claude handles the delegation.
- The skill follows a pipeline: **Ideation -> Research -> Synthesis -> PRD -> Implementation -> Review -> Testing**. Each stage uses the appropriate agent configuration.
- See [plugins/codex-orchestrator/README.md](plugins/codex-orchestrator/README.md) for full plugin documentation.
- ## Job Storage
- ```
- ~/.codex-agent/jobs/
- <jobId>.json # Job metadata
- <jobId>.prompt # Original prompt
- <jobId>.log # Full terminal output
- ```
- ## Tips
- - 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` (or `--clean`) to get parse-friendly output with ANSI and TUI chrome removed
- - Use `-r xhigh` for complex 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
- ## License
- MIT
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.