oh-my-codex-workflow

Oh My Codex (OMX) Workflow

Skill by ara.so — Codex Skills collection.

What OMX Does

Oh My Codex (OMX) is a workflow layer for OpenAI Codex CLI that enhances the base Codex experience with:

• Canonical workflow: $deep-interview → $ralplan → $ralph or $team
• Agent teams: Coordinated parallel execution with tmux-backed worktrees
• Persistent state: Plans, logs, memory, and mode tracking in .omx/
• Role keywords: Reusable specialist roles (executor, architect, reviewer, etc.)
• Skills system: Installable workflows like $deep-interview, $ralplan, $team, $ralph
• Project guidance: Scoped AGENTS.md for project-specific context
• Runtime hooks: Native Codex lifecycle integration via .codex/hooks.json

OMX keeps Codex as the execution engine and adds better task routing, workflow orchestration, and runtime support around it.

Installation

Prerequisites

• Node.js 20+
• Codex CLI: npm install -g @openai/codex
• Configured Codex auth (check with codex login status)
• tmux on macOS/Linux for team runtime (optional but recommended)

Install OMX

# Install both Codex CLI and OMX globally
npm install -g @openai/codex oh-my-codex

# Run setup to install prompts, skills, hooks, and scaffolding
omx setup

# Verify installation
omx doctor

# Smoke test actual Codex execution
omx exec --skip-git-repo-check -C . "Reply with exactly OMX-EXEC-OK"

Update OMX

# Check npm, install latest, and refresh setup
omx update

# Or manually:
npm install -g oh-my-codex
omx setup

Core Workflow

The Recommended Path

# 1. Launch OMX with recommended settings
omx --madmax --high

# Inside the Codex session:
# 2. Clarify scope (when boundaries are unclear)
$deep-interview "clarify the authentication change"

# 3. Create and approve implementation plan
$ralplan "approve the auth plan and review tradeoffs"

# 4a. Execute with persistent completion loop
$ralph "carry the approved plan to completion"

# OR 4b. Execute with coordinated parallel team
$team 3:executor "execute the approved plan in parallel"

# 5. Convert to durable goals (for multi-session work)
$ultragoal "turn this launch into durable Codex goals"

Launch Modes

# Default: auto-managed tmux on macOS/Linux interactive terminals
omx --madmax --high

# Direct mode (no OMX tmux/HUD management)
omx --direct --yolo

# Set persistent preference via environment
export OMX_LAUNCH_POLICY=direct  # or tmux, detached-tmux, auto
omx --yolo

# CLI flags override environment (last flag wins)
OMX_LAUNCH_POLICY=direct omx --tmux --yolo  # Uses tmux

Canonical Skills

$deep-interview

Clarify intent, boundaries, and non-goals when the request is vague.

$deep-interview "clarify requirements for the new API endpoint"
$deep-interview "understand the performance bottleneck before planning fixes"

$ralplan

Turn clarified scope into an approved architecture and implementation plan.

$ralplan "approve the implementation plan and review tradeoffs"
$ralplan "verify the migration strategy is safe"

$ralph

Persistent completion loop - one owner keeps pushing until done.

$ralph "carry the approved plan to completion"
$ralph "implement the auth changes with verification"

$team

Coordinated parallel execution with tmux-backed worktrees.

# Launch team with N agents of role:type
$team 3:executor "execute the approved plan in parallel"
$team 2:architect "design the new service architecture"

# Team management (CLI, not in-session)
omx team status <team-name>
omx team resume <team-name>
omx team shutdown <team-name>

$ultragoal

Convert a launch session into durable Codex goals for multi-session work.

$ultragoal "turn this migration into sequential Codex goals"

Project Structure

OMX creates and manages these directories:

.omx/
├── plans/           # Approved implementation plans from $ralplan
├── logs/            # Execution logs from $ralph and $team
├── memory/          # Persistent agent memory
├── ultragoal/       # Durable multi-goal artifacts
└── teams/           # Team runtime state and worktrees

.codex/
├── config.toml      # Codex configuration (OMX seeds defaults)
├── hooks.json       # Native Codex hooks (OMX-managed wrappers)
└── prompts/         # OMX-installed role and skill prompts

AGENTS.md            # Project-specific agent guidance (optional)

Configuration

Model and Environment Routing

Edit .omx-config.json for model/env routing (only use keys supported by your OMX version):

{
  "model": "gpt-5.5",
  "provider": "openai",
  "baseURL": "https://api.openai.com/v1",
  "env": {
    "OPENAI_API_KEY": "${OPENAI_API_KEY}"
  }
}

See model/env routing reference for details.

Codex Config Seeding

OMX seeds .codex/config.toml with recommended defaults for gpt-5.5:

[gpt-5.5]
model_name = "gpt-5.5"
model_context_window = 250000
model_auto_compact_token_limit = 200000

AGENTS.md Merge

Preserve existing project guidance while adding OMX sections:

# Merge mode: inserts between <!-- OMX:AGENTS:START --> / END -->
omx setup --merge-agents

# Default: skips existing AGENTS.md in non-interactive mode
omx setup

Common Patterns

Standard Workflow

// TypeScript example: typical OMX workflow pattern
async function standardWorkflow() {
  // 1. Clarify scope
  // Run: $deep-interview "understand the feature requirements"
  
  // 2. Create plan
  // Run: $ralplan "approve the implementation approach"
  
  // 3. Execute
  // Option A - single persistent owner:
  // Run: $ralph "implement with verification"
  
  // Option B - parallel team:
  // Run: $team 3:executor "execute in parallel"
  
  // 4. Convert to goals for multi-session work
  // Run: $ultragoal "create durable goals for remaining work"
}

Team Execution

# Launch team from CLI
omx team 3:executor "migrate database schema with verification"

# Check team status
omx team status migration-team

# Resume paused team
omx team resume migration-team

# Clean shutdown
omx team shutdown migration-team

Direct Codex Exec

// Use omx exec for one-off Codex calls outside a session
import { execSync } from 'child_process';

const result = execSync(
  'omx exec --skip-git-repo-check -C . "List all TypeScript files in src/"',
  { encoding: 'utf-8' }
);

console.log(result);

Custom Skill Creation

# Skills are stored in .codex/prompts/skills/
# Create a new skill file:
# .codex/prompts/skills/my-custom-skill.md

# Content structure:
# ---
# name: my-custom-skill
# triggers:
#   - do custom thing
# ---
# # Skill instructions
# When invoked, this skill should...

CLI Commands

Setup and Verification

omx setup                    # Install prompts, skills, hooks, scaffolding
omx setup --merge-agents     # Preserve existing AGENTS.md while adding OMX sections
omx setup --force            # Force overwrite existing files
omx doctor                   # Verify installation integrity
omx update                   # Check npm, install latest, refresh setup
omx uninstall                # Remove OMX-managed hooks (keep user hooks)

Launch

omx --madmax --high          # Recommended default
omx --yolo                   # Quick launch, less safety
omx --direct --yolo          # No OMX tmux management
omx --tmux                   # Force tmux mode

Execution

omx exec [options] "prompt"                    # Direct Codex execution
omx exec --skip-git-repo-check -C . "prompt"   # Skip git repo requirement

Team Runtime

omx team N:role "task"       # Launch N agents of role:type
omx team status <name>       # Check team status
omx team resume <name>       # Resume paused team
omx team shutdown <name>     # Clean shutdown
omx team list                # List active teams

Monitoring

omx hud --watch              # Launch monitoring HUD (operator surface)

Environment Variables

# Launch policy preference
export OMX_LAUNCH_POLICY=direct    # direct, tmux, detached-tmux, auto

# Codex home (affects plugin cache location)
export CODEX_HOME=~/.codex

# API keys (referenced in .omx-config.json)
export OPENAI_API_KEY=your_key_here
export ANTHROPIC_API_KEY=your_key_here

Troubleshooting

Installation Issues

# Verify setup
omx doctor

# Check Codex auth
codex login status

# Smoke test actual execution
omx exec --skip-git-repo-check -C . "Reply with exactly OMX-EXEC-OK"

# Refresh setup after version bump
omx setup

# Or use update to check npm first
omx update

Team Runtime Issues

# Verify tmux is installed
which tmux

# Check team status
omx team status <team-name>

# Review team logs
cat .omx/teams/<team-name>/logs/*

# Clean shutdown if stuck
omx team shutdown <team-name>

Hook Issues

# Verify hooks are registered
cat .codex/hooks.json

# Refresh OMX-managed hooks (preserves user hooks)
omx setup

# Check hook execution logs
cat .omx/logs/hooks/*

Model/Provider Issues

# Verify .omx-config.json routing
cat .omx-config.json

# Check Codex config
cat .codex/config.toml

# Test with direct exec
omx exec --skip-git-repo-check -C . "test prompt"

# Verify env vars are set
echo $OPENAI_API_KEY

Common Errors

Error: Codex not found

npm install -g @openai/codex

Error: Auth failed

codex login
codex login status

Error: tmux not found (team runtime)

# macOS
brew install tmux

# Linux
sudo apt-get install tmux  # or yum, dnf, etc.

Error: Setup refresh skips AGENTS.md

# Use merge mode to preserve existing content
omx setup --merge-agents

# Or force overwrite
omx setup --force

Advanced Usage

Plugin Mode vs Setup Mode

OMX ships both as npm package (setup mode) and Codex plugin (plugin mode):

Setup mode (recommended):

npm install -g oh-my-codex
omx setup

• Installs native agents and prompts
• Manages .codex/hooks.json wrappers
• Full runtime integration

Plugin mode:

• Install via Codex plugin marketplace
• Bundles skills in plugin manifest
• Optional MCP compatibility (disabled by default)
• Removes legacy OMX-managed prompts to avoid shadowing
• Native/runtime hooks still setup-owned
• Not a replacement for full OMX setup

Custom Agent Roles

Create custom roles in .codex/prompts/agents/:

---
name: security-reviewer
role: Security Review Specialist
---

# Security Reviewer Agent

You are a security review specialist. When assigned a task:

1. Review code for security vulnerabilities
2. Check for OWASP top 10 issues
3. Validate input sanitization
4. Review authentication/authorization
5. Document findings with severity levels

Integration with Other Tools

# Use OMX in CI/CD
omx exec --skip-git-repo-check -C . "Run security audit on changed files"

# Integrate with git hooks
# .git/hooks/pre-commit
#!/bin/bash
omx exec -C . "Review staged changes for issues"

Best Practices

1. Start with clarification: Use $deep-interview when scope is unclear
2. Approve plans explicitly: Always run $ralplan before execution
3. Choose the right execution mode: $ralph for persistent loops, $team for parallel work
4. Use durable goals: Run $ultragoal for multi-session work
5. Review .omx/ artifacts: Check plans and logs for context
6. Keep AGENTS.md updated: Maintain project-specific guidance
7. Verify with omx doctor: Run after setup or when issues arise
8. Test with omx exec: Smoke test auth and execution before workflows

Resources

• Website: https://oh-my-codex.dev
• GitHub: https://github.com/Yeachan-Heo/oh-my-codex
• Discord: https://discord.gg/PUwSMR9XNk
• Documentation:
  • Getting Started
  • Agents
  • Skills
  • Model/Env Routing