Oh My Codex

Name: Oh My Codex
Author: Yeachan-Heo

oh-my-codex (OMX) is a tool for orchestrating complex multi-agent workflows using OpenAI Codex CLI, enabling coordinated, parallel, and staged execution across diverse roles such as development, quality assurance, and domain expertise. It provides core functionalities like role prompts, workflow skills, persistent state management, and team operations, making it suitable for developers and teams working on intricate automation and code tasks. The skill supports advanced features like staged pipelines, hook extensions, environment configuration, and multi-agent team management for efficient, structured multi-step processes.

npx skills add https://github.com/supercent-io/skills-template --skill oh-my-codex

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

GitHub Owner

Owner: Yeachan-Heo

GitHub Links

Email: hurrc04@gmail.com