oh-my-codex-workflow

v2026.09.25
reason-machines/codex-skills00

Expert in Oh My Codex (OMX) - workflow layer for OpenAI Codex CLI with agents, skills, and team coordination

GitHub
Install command
npx skhub add reason-machines/oh-my-codex-workflow
Markdown
SKILL.md

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

Discovery
Tags

No tags published for this skill.

Version
Latest version metadata

Version

v2026.09.25

Published

Sep 25, 2026

Category

Uncategorized

License

NOASSERTION

Source path

skills/oh-my-codex-workflow

Default branch

main

Latest commit

901a4e3

Tree SHA

faa2fa4