Summary

This project provides codex-orchestrator, a tool for delegating tasks to OpenAI Codex agents, designed to integrate seamlessly with Claude Code. It enables users to spawn, monitor, and manage parallel coding agents via tmux sessions, significantly enhancing productivity for complex development workflows by separating AI-driven strategic planning from deep coding execution.

How It Works

The core mechanism involves the codex-agent CLI, which launches detached tmux sessions for each agent. These sessions execute the OpenAI Codex CLI, processing user-defined prompts. The system allows for live monitoring of agent activity, mid-task redirection via messages, and programmatic capture of results. When integrated as a Claude Code plugin, Claude Code handles the task decomposition and agent management, acting as the orchestrator.

Quick Start & Requirements

Installation is recommended via the Claude Code plugin marketplace (/plugin marketplace add kingbootoshi/codex-orchestrator, /plugin install codex-orchestrator). Alternatively, a manual CLI-only installation requires tmux (macOS/Linux), Bun (JavaScript runtime), the OpenAI Codex CLI (npm install -g @openai/codex), and an authenticated OpenAI account (codex --login). An automated installer script is also available. Platform support is limited to macOS and Linux; Windows users should utilize WSL.

Highlighted Details

• Codebase Context (--map): Utilizes a generated CODEBASE_MAP.md (created by the companion cartographer plugin) to provide agents with instant architectural understanding, drastically improving task precision and reducing exploration time.
• Parallel Agent Execution: Facilitates the simultaneous execution of multiple agents on different aspects of a project, such as security audits or refactoring tasks.
• Dynamic Agent Redirection: Allows for mid-task course correction or additional context injection using the codex-agent send command.
• Structured Job Data: The jobs --json command outputs detailed, parseable metadata including token consumption, modified files, and task summaries.

Maintenance & Community

The provided README does not contain specific details regarding maintainers, community channels (like Discord or Slack), or project roadmaps.

Licensing & Compatibility

The project is released under the MIT license, which is permissive and generally suitable for commercial use and integration into closed-source projects.

Limitations & Caveats

Platform support is restricted to macOS and Linux environments. The effectiveness of the codebase mapping feature relies heavily on the quality of the CODEBASE_MAP.md file generated by the separate cartographer plugin.