SKILL.md
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 doctorRecommended Launch Profile
# Trusted environment with high reasoning
omx --xhigh --madmax3. 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-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 executionPlugin 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 omxQuick 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