Skip to content
Back to search

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.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/kingbootoshi--codex-orchestrator/badge.svg)](/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

i

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)

  1. {
  2. "name": "codex-orchestrator-marketplace",
  3. "owner": {
  4. "name": "Bootoshi",
  5. "url": "https://github.com/kingbootoshi"
  6. },
  7. "metadata": {
  8. "description": "Delegate tasks to OpenAI Codex agents via tmux sessions. Designed for Claude Code orchestration.",
  9. "version": "1.0.0"
  10. },
  11. "plugins": [
  12. {
  13. "name": "codex-orchestrator",
  14. "source": "./plugins/codex-orchestrator",
  15. "description": "Orchestrate OpenAI Codex agents from Claude Code. Spawn parallel agents, monitor progress, send follow-up messages, and capture results - all through tmux sessions.",
  16. "version": "1.0.0",
  17. "category": "developer tools",
  18. "keywords": ["codex", "orchestration", "agents", "tmux", "parallel", "delegation"]
  19. }
  20. ]
  21. }
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)

  1. # Codex Orchestrator
  2. <p align="center">
  3. <img src="codex-agent-hero.jpeg" alt="Claude orchestrating Codex agents" width="600">
  4. </p>
  5. Delegate tasks to OpenAI Codex agents via tmux sessions. Designed for Claude Code orchestration.
  6. Spawn parallel coding agents, monitor their progress, send follow-up messages mid-task, and capture results - all from Claude Code or the command line.
  7. ## Installation
  8. ### As a Claude Code Plugin (Recommended)
  9. **Step 1:** Add the marketplace:
  10. ```
  11. /plugin marketplace add kingbootoshi/codex-orchestrator
  12. ```
  13. **Step 2:** Install the plugin:
  14. ```
  15. /plugin install codex-orchestrator
  16. ```
  17. **Step 3:** Restart Claude Code (may be required for the skill to load)
  18. **Step 4:** Install the CLI and dependencies:
  19. ```
  20. /codex-orchestrator init
  21. ```
  22. Or say "set up codex orchestrator" and Claude will walk you through it.
  23. **Step 5:** Use it - just ask Claude to do things. The skill activates automatically for coding tasks.
  24. ### Manual / CLI-Only Install
  25. If you just want the `codex-agent` CLI without the Claude Code plugin:
  26. ```bash
  27. # Prerequisites
  28. brew install tmux # macOS (or apt/pacman/dnf for Linux)
  29. npm install -g @openai/codex # OpenAI Codex CLI
  30. codex --login # Authenticate with OpenAI
  31. # Install
  32. git clone https://github.com/kingbootoshi/codex-orchestrator.git ~/.codex-orchestrator
  33. cd ~/.codex-orchestrator && bun install
  34. # Add to PATH (add this line to ~/.bashrc or ~/.zshrc)
  35. export PATH="$HOME/.codex-orchestrator/bin:$PATH"
  36. # Verify
  37. codex-agent health
  38. ```
  39. Or use the automated installer:
  40. ```bash
  41. 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
  42. ```
  43. ### Requirements
  44. | Dependency | Purpose | Install |
  45. |-----------|---------|---------|
  46. | [tmux](https://github.com/tmux/tmux) | Terminal multiplexer - agents run in tmux sessions | `brew install tmux` |
  47. | [Bun](https://bun.sh) | JavaScript runtime - runs the CLI | `curl -fsSL https://bun.sh/install \| bash` |
  48. | [Codex CLI](https://github.com/openai/codex) | OpenAI's coding agent - the thing being orchestrated | `npm install -g @openai/codex` |
  49. | OpenAI account | API access for Codex agents | `codex --login` |
  50. **Platform support:** macOS and Linux. Windows users should use WSL.
  51. ## Why?
  52. 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:
  53. - **Watch live** - Attach to any session and see exactly what the agent is doing
  54. - **Talk back** - Send follow-up messages mid-task to redirect or add context
  55. - **Run in parallel** - Spawn multiple agents investigating different parts of a codebase
  56. - **Capture results** - Grab output programmatically when agents finish
  57. 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.
  58. ## Codebase Map (Recommended)
  59. 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.
  60. Without a map, agents waste time exploring and guessing at structure. With a map, they know exactly where things are and start working immediately.
  61. The map is generated by [Cartographer](https://github.com/kingbootoshi/cartographer), a companion Claude Code plugin:
  62. ```
  63. /plugin marketplace add kingbootoshi/cartographer
  64. /plugin install cartographer
  65. /cartographer
  66. ```
  67. 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.
  68. ## Quick Start
  69. ```bash
  70. # Start an agent
  71. codex-agent start "Review this codebase for security vulnerabilities" --map
  72. codex-agent start "Refactor auth module" --wait --notify-on-complete 'printf "\033[0;32mCodex agent done\033[0m\n"'
  73. # Check status with structured JSON
  74. codex-agent jobs --json
  75. # See what it's doing
  76. codex-agent capture <jobId>
  77. # Redirect the agent mid-task
  78. codex-agent send <jobId> "Focus on the authentication module instead"
  79. ```
  80. ## Commands
  81. | Command | Description |
  82. |---------|-------------|
  83. | `start <prompt>` | Start a new agent with the given prompt |
  84. | `status <id>` | Check job status and details |
  85. | `send <id> <msg>` | Send a message to redirect a running agent |
  86. | `capture <id> [n]` | Get last n lines of output (default: 50) |
  87. | `output <id>` | Get full session output |
  88. | `attach <id>` | Print tmux attach command |
  89. | `watch <id>` | Stream output updates |
  90. | `jobs` | List all jobs |
  91. | `jobs --json` | List jobs with structured metadata (tokens, files, summary) |
  92. | `sessions` | List active tmux sessions |
  93. | `kill <id>` | Terminate a running job (last resort) |
  94. | `clean` | Remove jobs older than 7 days |
  95. | `health` | Check tmux and codex availability |
  96. ## Options
  97. | Option | Description |
  98. |--------|-------------|
  99. | `-r, --reasoning <level>` | Reasoning effort: `low`, `medium`, `high`, `xhigh` |
  100. | `-m, --model <model>` | Model name (default: gpt-5.4) |
  101. | `-w, --wait` | Wait for completion and emit a ping when done |
  102. | `--notify-on-complete <cmd>` | Shell command to run when the job completes |
  103. | `-s, --sandbox <mode>` | `read-only`, `workspace-write`, `danger-full-access` |
  104. | `-f, --file <glob>` | Include files matching glob (repeatable) |
  105. | `-d, --dir <path>` | Working directory |
  106. | `--map` | Include codebase map (docs/CODEBASE_MAP.md) |
  107. | `--strip-ansi` | Remove ANSI control codes and Codex TUI noise from output |
  108. | `--clean` | Alias for `--strip-ansi` |
  109. | `--json` | Output JSON (jobs command only) |
  110. | `--dry-run` | Preview prompt without executing |
  111. ## Jobs JSON Output
  112. Get structured job data with `jobs --json`:
  113. ```json
  114. {
  115. "id": "8abfab85",
  116. "status": "completed",
  117. "elapsed_ms": 14897,
  118. "tokens": {
  119. "input": 36581,
  120. "output": 282,
  121. "context_window": 258400,
  122. "context_used_pct": 14.16
  123. },
  124. "files_modified": ["src/auth.ts", "src/types.ts"],
  125. "summary": "Implemented the authentication flow..."
  126. }
  127. ```
  128. ## Examples
  129. ### Parallel Investigation
  130. ```bash
  131. # Spawn multiple agents to investigate different areas
  132. codex-agent start "Audit authentication flow" -r high --map -s read-only
  133. codex-agent start "Review database queries for N+1 issues" -r high --map -s read-only
  134. codex-agent start "Check for XSS vulnerabilities in templates" -r high --map -s read-only
  135. # Check on all of them
  136. codex-agent jobs --json
  137. ```
  138. ### Redirecting an Agent
  139. ```bash
  140. # Agent going down wrong path? Redirect it
  141. codex-agent send abc123 "Stop - focus on the auth module instead"
  142. # Agent needs info? Send it
  143. codex-agent send abc123 "The dependency is installed. Continue with typecheck."
  144. # Attach for direct interaction
  145. tmux attach -t codex-agent-abc123
  146. # (Ctrl+B, D to detach)
  147. ```
  148. ### With File Context
  149. ```bash
  150. # Include specific files in the prompt
  151. codex-agent start "Review these files for bugs" -f "src/auth/**/*.ts" -f "src/api/**/*.ts"
  152. # Include codebase map for orientation
  153. codex-agent start "Understand the architecture" --map -r high
  154. ```
  155. ## How It Works
  156. 1. You run `codex-agent start "task"`
  157. 2. It creates a detached tmux session
  158. 3. It launches the Codex CLI inside that session
  159. 4. It sends your prompt to Codex
  160. 5. It returns immediately with the job ID
  161. 6. Codex works in the background
  162. 7. You check with `jobs --json`, `capture`, `output`, or `attach`
  163. 8. You redirect with `send` if the agent needs course correction
  164. 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.
  165. ## The Claude Code Plugin
  166. When installed as a Claude Code plugin, the **codex-orchestrator skill** teaches Claude how to use the CLI automatically. Claude becomes the orchestrator:
  167. - Breaks your requests into agent-sized tasks
  168. - Spawns agents with the right flags (read-only for research, workspace-write for implementation)
  169. - Monitors agent progress
  170. - Synthesizes findings from multiple agents
  171. - Course-corrects agents that drift off-task
  172. This means you can just describe what you want, and Claude handles the delegation.
  173. The skill follows a pipeline: **Ideation -> Research -> Synthesis -> PRD -> Implementation -> Review -> Testing**. Each stage uses the appropriate agent configuration.
  174. See [plugins/codex-orchestrator/README.md](plugins/codex-orchestrator/README.md) for full plugin documentation.
  175. ## Job Storage
  176. ```
  177. ~/.codex-agent/jobs/
  178. <jobId>.json # Job metadata
  179. <jobId>.prompt # Original prompt
  180. <jobId>.log # Full terminal output
  181. ```
  182. ## Tips
  183. - Use `codex-agent send` to redirect agents - don't kill and respawn
  184. - Use `jobs --json` to get structured data (tokens, files, summary) in one call
  185. - Use `--strip-ansi` (or `--clean`) to get parse-friendly output with ANSI and TUI chrome removed
  186. - Use `-r xhigh` for complex tasks that need deep reasoning
  187. - Use `--map` to give agents codebase context (requires docs/CODEBASE_MAP.md)
  188. - Use `-s read-only` for research tasks that shouldn't modify files
  189. - Kill stuck jobs with `codex-agent kill <id>` only as a last resort
  190. ## License
  191. MIT

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.