oh-my-codex

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