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