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
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
- Plan: Strategic decomposition of work
- PRD: Product requirements definition
- Exec: Parallel execution by team workers
- Verify: Validation of deliverables
- Fix: Automated error resolution
6. Hook Extensions (v0.4.0+)
Native Lifecycle Events
session-start / session-end / session-idleturn-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
License
MIT License
