oh-my-codex (OMX) - Multi-Agent Orchestration for Codex CLI

When to use this skill

• Orchestrating complex multi-agent workflows with OpenAI Codex CLI
• Running parallel team workers in tmux for coordinated task execution
• Using persistent MCP servers for state, memory, and code intelligence
• Executing staged pipelines (plan → prd → exec → verify → fix)
• Leveraging role-based agent prompts for specialized tasks

---

Quick Start

Scenario: Platform setup for a Unity3D project

# Step 1: Install oh-my-codex
npm install -g oh-my-codex
omx setup

# Step 2: Confirm diagnostics pass
omx doctor

# Step 3: Launch and run your first Unity3D task
omx --xhigh --madmax
# Then inside Codex:
# $autopilot "scaffold a Unity3D input handler using the new Input System"

---

1. Core Concepts

Role Prompts (30 Agents)

Agent Tier	Agents	Use Case
Core Development	architect, planner, executor, debugger, verifier, explore	Main development workflow
Quality Assurance	style-reviewer, quality-reviewer, api-reviewer, security-reviewer, performance-reviewer	Code review lane
Domain Experts	dependency-expert, test-engineer, build-fixer, designer, writer, qa-tester	Specialized tasks
Product Strategy	product-manager, ux-researcher, product-analyst, information-architect	Product planning

Workflow Skills (40+)

Skill	Trigger	Description
autopilot	$autopilot	Full autonomous execution from idea to working code
ralph	$ralph	Self-referential loop with verifier verification until completion
ultrawork	$ulw	Maximum parallelism with parallel agent orchestration
team	$team	N coordinated agents using Codex CLI native teams
plan	$plan	Strategic planning with consensus and review modes
research	$research	Parallel scientist agents for comprehensive research
tdd	$tdd	Test-first development with red-green-refactor cycle
build-fix	$build-fix	Fix build errors, type errors, and toolchain failures
code-review	$code-review	Comprehensive code review across all quality dimensions
security-review	$security-review	Security audit focusing on vulnerabilities and trust boundaries
cancel	$cancel	Stop execution modes and clear active state

MCP Servers

Server	Purpose
omx_state	Persistent mode lifecycle state
omx_memory	Memory + notepad surfaces for long-running sessions
omx_code_intel	Code intelligence and context
omx_trace	Execution tracing and debugging

---

2. Installation & Setup

Prerequisites

• macOS or Linux (Windows via WSL2)
• Node.js >= 20
• Codex CLI installed (npm install -g @openai/codex)
• Codex auth configured

Install oh-my-codex

npm install -g oh-my-codex
omx setup
omx doctor

Recommended Launch Profile

# Trusted environment with high reasoning
omx --xhigh --madmax

---

3. Usage Patterns

Role Prompts (Inside Codex)

/prompts:architect "analyze current auth boundaries"
/prompts:executor "implement input validation in login"
/prompts:security-reviewer "audit OAuth flow"

Workflow Skills

$plan "ship OAuth callback safely"
$autopilot "implement user registration"
$team 3:executor "fix all TypeScript errors"

Team Mode (Terminal)

# Start parallel team workers
omx team 4:executor "parallelize a multi-module refactor"

# Monitor team status
omx team status <team-name>

# Resume team work
omx team resume <team-name>

# Shutdown team
omx team shutdown <team-name>

---

4. Launch Flags

Flag	Description
--yolo	Fast execution, minimal verification
--high	High reasoning effort
--xhigh	Extra-high reasoning effort
--madmax	Maps to Codex --dangerously-bypass-approvals-and-sandbox
--force	Force operation
--dry-run	Preview without execution
--verbose	Verbose output

---

5. Staged Pipeline

OMX implements a structured execution pipeline:

team-plan → team-prd → team-exec → team-verify → team-fix

1. Plan: Strategic decomposition of work
2. PRD: Product requirements definition
3. Exec: Parallel execution by team workers
4. Verify: Validation of deliverables
5. Fix: Automated error resolution

---

6. Hook Extensions (v0.4.0+)

Native Lifecycle Events

• session-start / session-end / session-idle
• turn-complete

Plugin Workflow

# Enable hook plugins
OMX_HOOK_PLUGINS=1 omx hooks test

# Hook commands
omx hooks init     # Initialize hooks
omx hooks status   # Check hook status
omx hooks validate # Validate configuration
omx hooks test     # Test hook execution

Plugin files: .omx/hooks/*.mjs

---

7. Configuration

AGENTS.md Injection

By default, OMX injects project-level AGENTS.md:

-c model_instructions_file="<cwd>/AGENTS.md"

Environment Controls

# Disable AGENTS.md injection
OMX_BYPASS_DEFAULT_SYSTEM_PROMPT=0 omx

# Custom instructions file
OMX_MODEL_INSTRUCTIONS_FILE=/path/to/instructions.md omx

---

Quick Reference

Command	Action
omx	Launch Codex with HUD
omx setup	Install prompts, skills, config wiring
omx doctor	Installation/runtime diagnostics
omx doctor --team	Team/swarm diagnostics
omx team <n>:<role> "<task>"	Start team workers
omx team status <name>	Show team status
omx team shutdown <name>	Shutdown team
omx status	Show active modes
omx cancel	Cancel execution modes
omx reasoning <mode>	Set reasoning (low/medium/high/xhigh)
omx hud	HUD display options
omx help	Show help

---

Resources

• Website: https://yeachan-heo.github.io/oh-my-codex-website/
• GitHub: https://github.com/Yeachan-Heo/oh-my-codex
• npm: https://www.npmjs.com/package/oh-my-codex

---

License

MIT License