home / skills / supercent-io / skills-template / oh-my-codex

oh-my-codex skill

unsafe

This skill orchestrates multi-agent Codex workflows, enabling parallel team execution, persistent state, and staged pipelines for reliable code delivery.

npx playbooks add skill supercent-io/skills-template --skill oh-my-codex

Review the files below or copy the command above to add this skill to your agents.

Files (1)

SKILL.md

6.1 KB

---
name: oh-my-codex
description: Multi-agent orchestration layer for OpenAI Codex CLI. Provides 30 specialized agents, 40+ workflow skills, team orchestration in tmux, persistent MCP servers, and staged pipeline execution.
allowed-tools: [Read, Write, Bash, Grep, Glob]
tags: [multi-agent, orchestration, codex, openai, team-mode, mcp-servers, workflow]
platforms: [Codex, Claude, Gemini]
version: 0.4.1
source: Yeachan-Heo/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
```bash
npm install -g oh-my-codex
omx setup
omx doctor
```

### Recommended Launch Profile
```bash
# Trusted environment with high reasoning
omx --xhigh --madmax
```

---

## 3. Usage Patterns

### Role Prompts (Inside Codex)
```text
/prompts:architect "analyze current auth boundaries"
/prompts:executor "implement input validation in login"
/prompts:security-reviewer "audit OAuth flow"
```

### Workflow Skills
```text
$plan "ship OAuth callback safely"
$autopilot "implement user registration"
$team 3:executor "fix all TypeScript errors"
```

### Team Mode (Terminal)
```bash
# 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
```

1. **Plan**: Strategic decomposition of work
2. **PRD**: Product requirements definition
3. **Exec**: Parallel execution by team workers
4. **Verify**: Validation of deliverables
5. **Fix**: Automated error resolution

---

## 6. Hook Extensions (v0.4.0+)

### Native Lifecycle Events
- `session-start` / `session-end` / `session-idle`
- `turn-complete`

### Plugin Workflow
```bash
# 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:
```bash
-c model_instructions_file="<cwd>/AGENTS.md"
```

### Environment Controls
```bash
# 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

Overview

This skill is a multi-agent orchestration layer for the OpenAI Codex CLI that coordinates specialized agents, staged pipelines, and team workers for complex software tasks. It provides 30 role-based agents, 40+ workflow skills, persistent MCP servers for state and code intelligence, and tmux-based team orchestration to run parallel workers. Use it to automate plan→execute→verify cycles and maintain long-running, stateful development sessions.

How this skill works

oh-my-codex launches a Codex CLI session enriched with role prompts and workflow skills. It manages persistent MCP servers (state, memory, code-intel, trace) to store context and trace execution across turns. Workflows run as staged pipelines or parallel teams in tmux, and hook plugins let you attach lifecycle events for custom automation.

When to use it

Orchestrating multi-step development pipelines (plan → prd → exec → verify → fix).
Running coordinated, parallel team workers to tackle large refactors or builds.
Maintaining long-lived project context, memory, and code intelligence across sessions.
Automating code review, security audits, and test-first development at scale.
Integrating custom hooks and plugins into agent lifecycles for CI-style workflows.

Best practices

Define clear role prompts and an AGENTS.md to guide agent behavior for your project.
Use team mode for parallelizable tasks and monitor progress with omx team status and omx team resume.
Favor staged pipeline execution (plan → exec → verify → fix) to separate design, implementation, and validation.
Start with conservative flags (--high) before using aggressive modes like --xhigh or --madmax. Use --dry-run to preview changes.
Persist MCP servers for long-running sessions to keep memory, traces, and code context available.

Example use cases

Autopilot an entire feature from idea to working code using $autopilot with staged verification.
Run a 4-person executor team in tmux to parallelize a multi-module refactor: omx team 4:executor "task".
Perform a comprehensive security audit using $security-review and the security-reviewer agent.
Execute TDD workflows with $tdd to generate tests, implement code, and refactor in red-green-refactor cycles.
Fix build errors and type failures automatically with $build-fix and build-fixer agents across CI runs.

FAQ

What platforms are supported?

macOS and Linux are supported natively; Windows can be used via WSL2.

What prerequisites are required?

Node.js >= 20 and the Codex CLI installed and configured. Then install oh-my-codex via npm and run omx setup.