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
- 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
- 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
- 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>
- 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
- 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
- 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
- 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