akillness 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
Instructions
Use the setup and workflow guidance below when installing or operating OMX inside a Unity3D-oriented Codex CLI environment.
Quick Start
npm install -g oh-my-codex
omx setup
omx doctor
$autopilot "scaffold a Unity input action wrapper with verification notes"
Examples
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
- 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
- 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