oh-my-codex (OMX) — User Guide

oh-my-codex (omx) is a multi-agent orchestration layer that sits on top of OpenAI Codex CLI and transforms it from a single-agent coding tool into a coordinated team of specialized AI agents. Version 0.13.1 (MIT license) adds team-based workflows, a skills catalog, a live heads-up display, MCP server integrations, multi-platform notifications, and automated research loops — all driven by the familiar omx command.

Note

oh-my-codex requires an existing OpenAI Codex CLI installation. It enhances Codex; it does not replace it.

1. Quick Start

Get from zero to a running multi-agent session in under five minutes.

Prerequisites checklist

Important

tmux is required for team mode. Without it, omx team will not start. On macOS install via brew install tmux; on Ubuntu/Debian use apt install tmux.

Install and initialize

# 1. Install globally
npm install -g oh-my-codex

# 2. Verify the binary is available
omx version

# 3. Bootstrap your project
cd /path/to/your/project
omx setup

omx setup creates:

• AGENTS.md — your team's shared instruction document
• Hook configuration files
• MCP server wiring

Run your first agent

# Check project health before doing anything complex
omx doctor

# Single-shot explore: ask a question about the codebase
omx explore "how does authentication work?"

# Start a two-executor team (requires tmux)
omx team 2:executor

Tip

Run omx doctor whenever something feels off. It checks Codex CLI availability, tmux, config files, and MCP server status in one shot.

2. Installation

Standard install (npm)

npm install -g oh-my-codex

After install, the omx binary is available globally. Verify:

omx version
# oh-my-codex v0.13.1

Project bootstrap

Every project needs its own setup. In each repo root:

omx setup

This is idempotent — safe to run again if you add teammates or reset config.

Warning

omx update overwrites AGENTS.md with a fresh template (GitHub issue #1671). Before running omx update in an existing project, back up your AGENTS.md:

cp AGENTS.md AGENTS.md.bak
omx update
# restore your customizations afterward

Build from source

git clone https://github.com/Yeachan-Heo/oh-my-codex.git
cd oh-my-codex
npm install
npm run build

Installing with Rust native binaries (optional)

If you have a Rust toolchain installed, omx can build native binaries for faster execution of certain components. This is entirely optional; the TypeScript-only install is fully functional.

# Confirm Rust toolchain is available
rustc --version
cargo --version

# Build native binaries
cargo build --release

The Rust crates include omx-explore (sandboxed codebase exploration), omx-sparkshell (shell-native lookups), omx-mux (tmux multiplexer), and omx-runtime (standalone runtime).

Note

The omx-explore native harness is not available on Windows due to POSIX shell dependencies. Use omx sparkshell or set OMX_RUNTIME_BINARY to a custom harness path.

Uninstalling

omx uninstall
npm uninstall -g oh-my-codex

omx uninstall removes omx configuration artifacts. The npm uninstall removes the binary.

3. Configuration

AGENTS.md — the team instruction file

AGENTS.md (in your project root) is the primary configuration surface. Every agent in a team session reads this file before starting work. Write it in plain Markdown. Treat it as the "team charter":

# Project: MyApp

## Architecture
- Backend: FastAPI on port 8000
- Frontend: React in `web/`
- Database: PostgreSQL

## Code conventions
- Use type hints everywhere in Python
- Components go in `web/src/components/`
- Tests must cover happy path + at least one error path

## Off-limits
- Do NOT modify `db/migrations/` without explicit instruction

Tip

Use omx agents-init to generate a starter AGENTS.md tailored to your repo structure. Use omx deepinit [path] for a deeper scan that produces richer initial content.

Notification configuration

Configure one or more notification platforms so omx can alert you when long-running tasks complete:

Discord webhook (simplest):

export OMX_DISCORD_WEBHOOK_URL="https://discord.com/api/webhooks/..."

Discord bot (supports replies back to the session):

export OMX_DISCORD_NOTIFIER_BOT_TOKEN="Bot ..."
export OMX_DISCORD_NOTIFIER_CHANNEL="1234567890"
export OMX_DISCORD_MENTION="@YourUsername"

Telegram:

export OMX_TELEGRAM_BOT_TOKEN="123456:ABC-..."
export OMX_TELEGRAM_CHAT_ID="-100..."

Slack:

export OMX_SLACK_WEBHOOK_URL="https://hooks.slack.com/services/..."
export OMX_SLACK_MENTION="@channel"

Set these in your shell profile (.bashrc, .zshrc) or in a project-level .env file sourced before running omx. Or use the guided setup:

omx skill configure-notifications

MCP server configuration

omx bundles five MCP servers that auto-start with each session:

To disable a server's auto-start, set its disable variable before launching:

export OMX_WIKI_SERVER_DISABLE_AUTO_START=true
export OMX_TRACE_SERVER_DISABLE_AUTO_START=true

Replace WIKI / TRACE with the uppercase server name for other servers.

Note

MCP server processes can accumulate as duplicate siblings if sessions are not cleanly terminated (GitHub issue #1665). Run omx cleanup periodically to reap stale processes.

Hook configuration

The OMX_HOOK_CONFIG environment variable points to your hook configuration file. Hooks are managed via omx hooks subcommands (see Section 4.10). The OMX_HOOK_DERIVED_SIGNALS variable enables signal-derived hook triggers.

Key environment variables reference

The full set of 67 configuration keys is documented in Section 4.14. The most commonly needed variables are:

4. Core Usage

4.1 omx team — Multi-Agent Team Mode

Team mode is the headline feature: multiple specialized agents work in parallel inside a tmux session, coordinated by a leader.

Basic syntax:

omx team [spec...]

Each spec is N:agent-type where N is the number of agents of that type:

# Three executors (default workhorse configuration)
omx team 3:executor

# One planner + two executors + one verifier
omx team 1:planner 2:executor 1:verifier

# Focused review session
omx team 1:architect 1:executor 1:code-reviewer

# Full quality pipeline
omx team 1:planner 3:executor 1:verifier 1:security-reviewer

When launched, omx:

1. Opens a tmux session with one pane per agent
2. Starts a leader agent that distributes tasks
3. Agents pick up jobs from the shared queue, execute, and submit results
4. The HUD (if running) shows live progress

Important

tmux must be installed and accessible in your PATH. omx creates and manages the tmux session — do not manually kill agent panes while a session is active.

Available agent types for teams:

Team environment variables:

Caution

OMX_TEAM_AUTO_ACCEPT_BYPASS bypasses all confirmation prompts in agent workflows (GitHub issue #1651). This should be opt-in per session, not set globally in your shell profile. An unintended bypass in the wrong session could allow agents to make destructive changes without confirmation.

4.2 omx explore — Codebase Search

Sandboxed read-only exploration: omx launches a Codex agent with no write permissions to answer questions about your codebase.

omx explore "where is the database connection pool configured?"
omx explore "what does the authentication middleware do?"
omx explore "list all API endpoints that accept file uploads"
omx explore "trace the call chain from HTTP request to database write for POST /users"

The agent reads source files, traces call graphs, and returns a structured answer. No files are modified.

Model control:

export OMX_DEFAULT_SPARK_MODEL="gpt-4o"
export OMX_SPARKSHELL_FALLBACK_MODEL="gpt-4o-mini"
export OMX_DEFAULT_FRONTIER_MODEL="gpt-4o"

Skill alias: omx skill deepsearch routes to explore.

4.3 omx sparkshell — AI-Summarized Command Output

Run any shell command and receive an AI-generated summary of what the output means:

omx sparkshell "npm test"
omx sparkshell "git log --oneline -20"
omx sparkshell "docker ps -a"
omx sparkshell "cat error.log | tail -100"
omx sparkshell "npm audit"

omx runs the command, captures stdout/stderr, and sends both to the configured model for a human-readable interpretation.

Relevant variables:

4.4 omx ralph — Verification Loop

Ralph is an iterative quality loop: the agent executes, verifies its own output against defined acceptance criteria, and retries until the criteria pass or a stop condition is reached.

omx ralph

Use ralph for tasks where correctness is critical and you want the agent to self-check:

• Fixing a failing test suite (loop until tests are green)
• Implementing a feature with a clear spec (loop until all criteria pass)
• Debugging a reproducible error (loop until the error is gone)

Note

The underlying withRalphSteerLock mechanism retries indefinitely if the stop condition is never satisfied (GitHub issue #1653). Always provide a concrete, binary acceptance criterion: "exit when npm test returns exit code 0" works; "exit when the code looks better" does not.

Via skill shortcut: omx skill ralph

Related planning modes:

• omx skill plan — create a plan without executing
• omx skill ralplan — plan then execute with ralph-style verification

4.5 omx autoresearch — Automated Research Loops

Launch a fully automated experiment or research mission:

omx autoresearch

omx prompts for a mission description, then runs a loop: hypothesize → experiment → observe → refine. Useful for:

• Benchmarking different implementation approaches
• Exploring whether a library solves a problem
• Running systematic code quality improvements across a large codebase

Always provide a quantitative stop condition (e.g., "run 5 iterations" or "stop when benchmark improves by 20%").

4.6 omx hud — Heads-Up Display

Live dashboard showing agent status, job queue, and session metrics:

# Basic HUD
omx hud

# Watch mode (auto-refresh)
omx hud --watch

# JSON output (for scripting/piping)
omx hud --json

# Named preset layout
omx hud --preset=compact
omx hud --preset=full

# tmux-integrated display
omx hud --tmux

Tip

Run omx hud --watch in a spare terminal pane to monitor a running team session in real time without attaching to the tmux session itself.

Via skill shortcut: omx skill hud

4.7 Skills — Shortcut Commands

Skills are pre-configured task templates invoked via omx skill <name>. They wrap common workflows so you don't have to construct exact subcommand syntax.

omx skill <skill-name>

Core execution skills:

Planning skills:

Review and analysis skills:

Development task skills:

AI provider skills:

Utility skills:

Deprecated aliases (still functional):

4.8 omx ask — Direct AI Queries

Ask a question directly to an alternative AI provider without going through the full Codex pipeline:

omx ask claude "explain the tradeoffs between these two approaches"
omx ask gemini "what's the best way to implement rate limiting in Go?"

4.9 Agent Management

List all defined agent roles:

omx agents list

Add a custom agent:

omx agents add

Edit an existing agent definition:

omx agents edit <agent-name>

Remove an agent:

omx agents remove <agent-name>

Bootstrap AGENTS.md files:

# Generate in current directory
omx agents-init

# Generate for a specific path
omx agents-init /path/to/project

# Deep scan for richer initial content
omx deepinit /path/to/project

4.10 Hook Management

Hooks inject behavior at defined points in the agent lifecycle (before/after execution, on job completion, etc.):

# List configured hooks
omx hooks list

# Add a hook
omx hooks add

# Edit a hook
omx hooks edit <hook-name>

# Remove a hook
omx hooks remove <hook-name>

The OMX_HOOK_CONFIG environment variable points to your hook configuration file.

4.11 State Management

Read and write mode state that persists across invocations within a session:

# Read current state value
omx state get <key>

# Write state
omx state set <key> <value>

State is used internally by team mode to coordinate between agents via the state MCP server.

4.12 Session History Search

Search past session outputs:

omx session search "authentication bug"
omx session search "migration script"
omx session search "rate limiting"

4.13 Adapters

Adapters connect omx to external AI systems beyond OpenAI Codex:

# Adapter management
omx adapt <target> <subcommand>

# OpenClaw adapter
omx adapt openclaw <subcommand>

# Hermes adapter
omx adapt hermes <subcommand>

OpenClaw environment variables:

4.14 Full Environment Variable Reference

All 67 configuration keys organized by category:

Team coordination:

Notifications:

Reply listener:

OpenClaw adapter:

Explore and SparkShell:

General:

4.15 Maintenance Commands

# Health check — always the first thing to run when something is wrong
omx doctor

# Clean stale state and zombie processes
omx cleanup

# Update omx to the latest version
omx update

# Show current version
omx version

# Remove omx from the system
omx uninstall

5. Common Tasks

Real-world recipes for using omx on large codebases.

Task 1: Understand an unfamiliar codebase

cd /path/to/unknown-project
omx setup
omx explore "give me a high-level overview — what does this codebase do and how is it structured?"
omx explore "what are the main entry points and how does data flow through the system?"
omx explore "what are the external dependencies and integrations?"

Task 2: Fix a failing test suite

# Use ralph to loop until all tests pass
omx skill ralph
# When prompted, describe the goal:
# "Run npm test and fix all failures. Stop when npm test exits with code 0."

Task 3: Security audit a new dependency or PR

omx skill security-review
# The security-reviewer agent flags auth issues, injection risks,
# secrets in code, insecure defaults, and vulnerable patterns

Task 4: Refactor a large module in parallel

# Planner breaks the work, executors work in parallel, verifier confirms correctness
omx team 1:planner 3:executor 1:verifier
# In the leader pane: describe the refactor goal clearly

Task 5: Generate or improve documentation

omx team 1:writer 1:analyst
# Writer reads code, analyst provides technical context
# Or use a single writer for smaller documentation tasks
omx team 1:writer

Task 6: Add tests for uncovered code

omx skill tdd
# Routes to test-engineer agent
# Describe the module and coverage goal when prompted

Task 7: Debug a production error from logs

# Step 1: Get AI interpretation of the log
omx sparkshell "cat /var/log/app/error.log | tail -200"

# Step 2: Launch a debugger for root-cause analysis
omx team 1:debugger

Task 8: Review a pull request

# Quick review via skill
omx skill review

# Full multi-perspective review
omx team 1:code-reviewer 1:security-reviewer 1:api-reviewer

Task 9: Fix a broken build

omx skill build-fix
# Routes to build-fixer agent
# Paste the error message when prompted

Task 10: Audit code style and apply fixes

omx team 1:style-reviewer 1:executor
# Style reviewer flags violations, executor applies fixes

Task 11: Performance profiling and optimization

omx team 1:performance-reviewer 1:executor
# Reviewer identifies hot paths and bottlenecks,
# executor implements and measures optimizations

Task 12: Dependency upgrade assessment

omx team 1:dependency-expert
# Reviews all dependencies, flags outdated or vulnerable packages,
# proposes upgrade plan with risk assessment per package

Task 13: API design review

omx team 1:api-reviewer 1:product-analyst
# API reviewer checks consistency, versioning, error handling, docs;
# product analyst evaluates developer experience

Task 14: Search for a problematic pattern across the codebase

omx explore "find all places where SQL queries are constructed by string concatenation"
omx explore "list every location that reads credentials from environment variables"
omx explore "find all unhandled promise rejections"

Task 15: Automated research experiment

omx autoresearch
# Mission example:
# "Compare three approaches to rate limiting: token bucket, sliding window, 
#  and fixed window. Implement each and benchmark with 1000 req/s load.
#  Run 3 iterations. Stop after iteration 3 and report results."

Task 16: Set up notifications for a long-running team session

export OMX_DISCORD_WEBHOOK_URL="https://discord.com/api/webhooks/..."
export OMX_NOTIFY_VERBOSITY="high"
omx team 4:executor
# Notifications fire when jobs complete, agents get stuck, or errors occur

Task 17: Trace a full request lifecycle

omx explore "trace the complete request lifecycle for POST /api/v1/users — from HTTP handler through validation, business logic, database writes, and HTTP response"

Task 18: Clean up AI-generated code

omx skill ai-slop-cleaner
# Removes AI artifacts: unnecessary comments, placeholder text,
# redundant type annotations, overly verbose variable names

Task 19: Replicate or clone a UI from a design or URL

omx skill web-clone
# Provide the target URL or design spec;
# the designer/writer agents build a functional replica

Task 20: Git history archaeology

omx skill git-master
# Routes to git-master agent; example prompt:
# "Find the commit that introduced the authentication bypass between v1.2 and v1.5
#  and explain what changed"

Task 21: Monitor a running team session from a separate terminal

# In a second terminal pane or window — does not attach to the tmux session
omx hud --watch

Task 22: Search session history for past outputs

omx session search "database migration 2024"
omx session search "rate limiting implementation"
omx session search "auth refactor"

Task 23: Pre-deploy health check

omx doctor
omx sparkshell "npm run build 2>&1"
omx sparkshell "npm test 2>&1"

Task 24: Requirements gathering for a new feature

omx skill deep-interview
# The agent conducts structured Q&A to clarify requirements,
# edge cases, constraints, and success criteria —
# then produces a spec document you can hand to executors

Task 25: Full-scale parallel implementation sprint

# Maximum parallelism: plan → execute → verify → review
omx team 1:planner 4:executor 1:verifier 1:code-reviewer
# Planner breaks the epic into independent units;
# executors work simultaneously;
# verifier checks outputs;
# code-reviewer signs off on quality

6. Troubleshooting

Error reference (25+ entries)

Error: omx: command not found Cause: npm global bin directory not in PATH, or install failed silently. Solution:

npm install -g oh-my-codex
# Find the global bin directory:
npm bin -g
# Add it to PATH in your .bashrc/.zshrc:
export PATH="$(npm bin -g):$PATH"
source ~/.bashrc

Prevention: After installing any global npm package, confirm npm bin -g is in PATH.

Error: omx exits immediately with [exited] on macOS Cause: macOS shells use /bin/sh -c to background the Codex process, which loses stdin TTY inheritance (GitHub issue #1643). Solution: Launch omx from a proper terminal emulator (iTerm2 or Terminal.app), not from a script. Ensure you are in a full interactive shell session. Prevention: Never launch omx team from a non-interactive shell or via SSH without TTY allocation. For SSH, use ssh -t user@host "omx team ...".

Error: omx team leader pane shows "stuck" immediately after startup Cause: Child process startup race condition — the leader pane shows stale state while workers are still initializing (GitHub issue #1635). Solution: Wait 15–30 seconds. The UI updates once all workers report ready. If still stuck after 60 seconds, run omx cleanup and restart. Prevention: Do not interact with the leader pane immediately after omx team launches.

Error: MCP server processes accumulate / duplicate sibling processes appear Cause: Sessions terminated without clean shutdown leave MCP server processes running (GitHub issue #1665). Solution:

omx cleanup

Prevention: Always allow omx to exit cleanly via Ctrl-C in the leader pane, rather than killing the tmux session or closing the terminal window.

Error: omx update overwrites AGENTS.md with a blank template Cause: The update process replaces AGENTS.md (GitHub issue #1671). Solution: Restore from version control: git checkout AGENTS.md. Or restore from backup. Prevention: Always commit AGENTS.md to git before omx update. Manual backup: cp AGENTS.md AGENTS.md.bak.

Error: Reply listener sends raw escape codes or garbled output to Discord/Telegram Cause: The reply listener captures unfiltered tmux pane content including terminal escape sequences (GitHub issue #1661). Solution: Disable reply mode until the upstream fix ships:

export OMX_REPLY_ENABLED=false

Prevention: Only enable reply mode after confirming your notification channel renders plain text cleanly.

Error: Stale notify fallback process sends SIGTERM to a wrong or unrelated process Cause: reapStaleNotifyFallbackWatcher sends SIGTERM without verifying process identity (GitHub issue #1657). Solution: Run omx cleanup to clear all fallback watchers, then restart the session. Prevention: Avoid running multiple concurrent omx sessions in the same project directory.

Error: ralph loop never terminates Cause: withRalphSteerLock retries indefinitely when the stop condition is never satisfied (GitHub issue #1653). Solution: Interrupt with Ctrl-C. Re-run ralph with a specific, binary, checkable acceptance criterion. Prevention: Always provide a concrete stop condition. "Exit when npm test returns exit code 0" works. "Exit when it looks good" does not.

Error: Stream error or connection dropped mid-session Cause: Network instability, OpenAI API timeout, or Codex CLI connection failure (GitHub issue #1677). Solution: Check session progress via omx hud and omx state get. If the session captured partial work, you may be able to resume by re-running with the same context. Otherwise restart. Prevention: Run long sessions on a stable wired connection. Configure a fallback model:

export OMX_SPARKSHELL_FALLBACK_MODEL="gpt-4o-mini"

Error: stateDirToProjectRoot resolves to the wrong directory Cause: The internal function hardcodes a directory-depth assumption that breaks for non-standard project layouts (GitHub issue #1654). Solution: Ensure your project root is a standard git repository with .git/ at root level. Avoid nested git repos. Prevention: Always run omx setup from the actual project root, not a subdirectory.

Error: Leader UI lags or freezes during long sessions Cause: Git polling for leader activity status runs synchronously and blocks the Node.js event loop (GitHub issue #1656). Solution: This is an upstream bug. Workaround: compact the git object store before starting a team session in a large repo:

git gc --aggressive

Prevention: For repositories with very large history (>50k commits), expect some lag until the upstream fix ships.

Error: path-to-regexp or hono vulnerability warnings from npm audit Cause: Transitive dependency vulnerabilities: path-to-regexp HIGH severity ReDoS, hono MODERATE (GitHub issue #1660). Solution:

npm audit fix

If no automated fix is available, monitor the upstream issue and update omx when a patched release ships. Prevention: Run npm audit after every omx update.

Error: omx doctor reports "codex CLI not found" Cause: OpenAI Codex CLI not installed or not in PATH. Solution:

npm install -g @openai/codex
codex --version

Prevention: Install Codex CLI before installing omx. Verify codex --version works before running omx setup.

Error: Discord notifications not arriving Cause: Webhook URL incorrect, bot token invalid, or bot lacks channel permissions. Solution:

# Test the webhook directly
curl -X POST "$OMX_DISCORD_WEBHOOK_URL" \
  -H "Content-Type: application/json" \
  -d '{"content": "omx test notification"}'

Check Discord channel permissions if using a bot token. Verify the bot has Send Messages permission. Prevention: Run omx skill configure-notifications to validate credentials before starting a long session.

Error: Telegram notifications not arriving Cause: OMX_TELEGRAM_BOT_TOKEN or OMX_TELEGRAM_CHAT_ID incorrect, or bot not added to the chat. Solution: Verify the bot is a member of the target chat. Retrieve the correct chat ID:

curl "https://api.telegram.org/bot$OMX_TELEGRAM_BOT_TOKEN/getUpdates"

The chat.id field in the response is what you need for OMX_TELEGRAM_CHAT_ID. Prevention: Test delivery via omx skill configure-notifications before starting a production session.

Error: omx explore returns sparse or unhelpful answers Cause: AGENTS.md missing or too thin — the explore agent lacks project context. Solution:

omx agents-init      # or for deeper analysis:
omx deepinit

Then retry the query. Prevention: Always populate AGENTS.md with architecture, conventions, and key directories before using explore on a new project.

Error: Team mode agents can't communicate / jobs not being picked up by workers Cause: OMX_TEAM_STATE_ROOT or OMX_JOBS_DIR points to a non-writable or non-existent directory. Solution:

ls -la $OMX_TEAM_STATE_ROOT
ls -la $OMX_JOBS_DIR
# Fix permissions, or unset to restore defaults:
unset OMX_TEAM_STATE_ROOT
unset OMX_JOBS_DIR

Prevention: Only set these variables if you have a specific reason to override defaults.

Error: omx sparkshell times out before returning the summary Cause: OMX_SPARKSHELL_SUMMARY_TIMEOUT_MS is too low for the model's response latency, or the command output is very large. Solution:

export OMX_SPARKSHELL_SUMMARY_TIMEOUT_MS=120000  # 2 minutes
export OMX_SPARKSHELL_LINES=200                  # limit lines sent to model

Prevention: For commands that produce large output, filter before passing to sparkshell:

omx sparkshell "npm test 2>&1 | grep -E 'FAIL|PASS|Error' | tail -50"

Error: omx autoresearch loop runs indefinitely Cause: Mission statement is too vague for the agent to determine when the experiment is complete. Solution: Interrupt with Ctrl-C. Restate the mission with a quantitative stop condition. Prevention: Always include a concrete termination condition: "Run N iterations" or "Stop when metric X exceeds threshold Y."

Error: omx hud --watch shows no data or all zeros Cause: No active team session, or OMX_TEAM_STATE_ROOT mismatch between the team session and hud invocation. Solution: Ensure you run omx hud from the same directory (same effective OMX_TEAM_STATE_ROOT) as the running team session. Prevention: Run omx hud from the project root where the team session was started.

Error: omx cleanup does not stop all zombie processes Cause: Processes owned by a different user, or processes that have reparented to PID 1. Solution:

pkill -f "omx-runtime"
pkill -f "codex"

Prevention: Exit sessions cleanly via Ctrl-C in the leader pane rather than forcibly closing terminal windows or killing tmux.

Error: Unrecognized skill name / omx skill not found Cause: Typo in skill name, or using a skill name that was removed in a recent version. Solution:

omx skill help    # list all current skills
omx skill skill   # same catalog view

Prevention: Refer to the skills table in Section 4.7. Deprecated aliases (ultraqa, swarm, ecomode) are still supported.

Error: Stale state from a previous crashed session interferes with a new one Cause: Partial state files left in OMX_TEAM_STATE_ROOT from a crash. Solution:

omx cleanup
omx state get status   # verify state is clear

Prevention: Run omx cleanup as standard pre-flight before every team session.

Error: omx setup overwrites existing hook configuration files Cause: Setup recreates hook files on each run. Solution: Restore from git: git checkout <hook-config-file>. Or diff against the backup and re-apply your customizations. Prevention: Track all hook config files in git. Run git stash before omx setup if you have uncommitted hook changes.

Error: Team mode starts but agents are idle and no tasks run Cause: No task was provided to the leader, or the leader prompt was ambiguous. Solution: In the leader tmux pane, type a clear, actionable task description and confirm. The leader will break it into jobs and dispatch to workers. Prevention: Have your task description ready before launching omx team. Paste it into the leader pane within the first 30 seconds.

7. FAQ

Installation and Requirements

Q: Do I need a Rust toolchain to use omx? No. Rust is optional and only required if you want native binary builds (omx-explore, omx-sparkshell, omx-mux, omx-runtime). The full omx feature set works with Node.js only.

Q: What Node.js version is required? Node.js 20 or higher. Check with node --version. If you need to upgrade, use nvm (Node Version Manager).

Q: Is tmux required for all omx features? No. tmux is only required for omx team (multi-agent team mode). omx explore, omx sparkshell, omx ralph, omx autoresearch, omx hud, omx skill, omx ask, and all agent management commands work without tmux.

Q: Does omx work on Windows? Team mode requires tmux, which has limited Windows support. Use WSL (Windows Subsystem for Linux) with tmux installed in the Linux environment. Single-agent modes may work natively in some configurations.

Q: Does omx work on macOS? Yes, with one caveat: team mode may exit immediately with [exited] on macOS due to TTY inheritance handling (GitHub issue #1643). Launch from iTerm2 or Terminal.app in an interactive shell.

Q: Can I use omx without OpenAI Codex CLI? No. omx is an orchestration layer on top of Codex CLI. Codex CLI must be installed and configured with a valid API key.

Skills and Agents

Q: What's the difference between a skill and an agent? An agent is a defined role with a specific behavior profile (executor, planner, debugger, etc.). A skill is a shortcut that launches one or more agents pre-configured for a common task pattern. Agents are the workers; skills are convenience entry points.

Q: Can I create custom agents? Yes. Use omx agents add to define a new agent role, or edit existing definitions with omx agents edit <name>.

Q: What's the difference between ralph and autopilot? autopilot is continuous autonomous execution with minimal interruption. ralph is a verification loop: it executes, checks its own output against acceptance criteria, and retries if the check fails. Use ralph when correctness matters more than speed.

Q: What does ultrawork do differently than autopilot? ultrawork is optimized for high throughput across many parallel independent tasks. autopilot is for sustained single-agent execution of complex tasks. Use ultrawork for large batches; use autopilot for one long, complex task. (ecomode is a deprecated alias for ultrawork.)

Q: Is swarm the same as team? Yes. swarm is a deprecated alias that routes to team. Use omx team in new workflows.

Q: What is sisyphus-lite? A persistent retry agent role — like Sisyphus, it keeps trying. Use it for tasks that may fail repeatedly but should keep going (e.g., a flaky build that needs to be retried against an unreliable external service).

Team Mode

Q: How many agents can I run in parallel? No hard limit is set in omx. Practical limits are your system RAM, the API rate limits on your OpenAI account, and the number of tmux panes readable at once. Three to five executors is a good starting point for most codebases.

Q: How do agents coordinate — do they share files directly? Agents coordinate through the shared state MCP server and the job queue in OMX_JOBS_DIR. The leader distributes jobs; workers pick them up atomically to prevent double-claiming. Agents do not write to each other's working files directly.

Q: Can I add more agents to a running team session? No. The team composition is fixed at launch. To scale up or change composition, stop the current session and relaunch with a new spec.

Q: What happens if an agent crashes mid-task? The job remains in the queue in an in-progress state. The leader eventually detects the stalled job and either retries or flags it. Run omx cleanup to force-clear stale jobs.

Q: Can I use different AI models for different agent types? Yes. OMX_TEAM_WORKER_CLI_MAP maps agent types to specific CLI commands. Configure the CLI command to use a particular model for each agent type, allowing cheap models on simple roles and expensive models on complex ones.

Q: How do I pass a task to the team after launching? Type the task description into the leader tmux pane and press Enter. The leader breaks it into subtasks and dispatches them to workers.

Notifications

Q: Which notification platforms are supported? Discord (via webhook or bot token), Telegram, and Slack.

Q: Can I use multiple notification platforms at once? Yes. Set environment variables for each platform. omx dispatches to all configured platforms simultaneously.

Q: What does OMX_NOTIFY_VERBOSITY control? Granularity of notifications. At high verbosity, each job completion and error triggers a notification. At low verbosity, only session-level events (complete, critical error) do.

Q: What is OMX_DISPATCH_COOLDOWN_SECONDS? A rate-limiting floor that prevents notification spam. If multiple events fire within the cooldown window, they are batched or the later ones are suppressed.

Q: What is the reply feature? When OMX_REPLY_ENABLED=true, the reply listener watches your notification channel for messages from configured user IDs, then routes those messages back to the running session as steering inputs. This lets you guide a team session from Discord/Telegram/Slack without sitting at the terminal.

Q: The reply listener sends garbled output to my channel. What's wrong? This is a known issue (GitHub issue #1661) — raw tmux pane content including escape codes goes to the channel. Disable reply mode: export OMX_REPLY_ENABLED=false.

MCP Servers

Q: What are the MCP servers used for? They provide structured services to agents: state enables shared coordination between team agents; memory persists information across sessions; code_intel provides symbol lookup and reference tracking; trace enables execution tracing; wiki provides a project knowledge base accessible to all agents.

Q: Do MCP servers require separate installation or configuration? No. They are bundled with omx and start automatically. No configuration is required for default operation.

Q: How do I disable a specific MCP server?

export OMX_<SERVERNAME>_SERVER_DISABLE_AUTO_START=true
# Example:
export OMX_WIKI_SERVER_DISABLE_AUTO_START=true

Q: Why do MCP server processes keep accumulating? This is a known upstream issue (GitHub issue #1665). Run omx cleanup after every session. The issue is tracked for a fix in a future release.

Configuration and Environment

Q: Where should I store environment variables? For global settings: your shell profile (.bashrc or .zshrc). For project-specific settings: a project-level .env file that you source before running omx (source .env). Never commit .env files containing API keys or tokens to git.

Q: What is CODEX_HOME? The directory where Codex CLI stores its configuration, session history, and model settings. omx respects this variable if set.

Q: Can I have different configurations for different projects? Yes. AGENTS.md is per-project. Use direnv or a project-level .env to set per-project environment variables for notification channels, model preferences, etc.

Q: What is OMX_NOTIFY_PROFILE? A named notification profile that groups settings (which platforms to use, verbosity level, etc.). Useful when you have different contexts — e.g., a "quiet" profile for routine runs and a "loud" profile for critical deployments.

Maintenance and Updates

Q: How do I update omx?

omx update

Warning

This overwrites AGENTS.md. Back up first: git commit AGENTS.md or cp AGENTS.md AGENTS.md.bak.

Q: How do I know which version I have?

omx version
# oh-my-codex v0.13.1

Q: Is auto-update enabled by default? Controlled by OMX_AUTO_UPDATE. Check with echo $OMX_AUTO_UPDATE. To disable: export OMX_AUTO_UPDATE=false.

Q: How do I completely remove omx?

omx uninstall
npm uninstall -g oh-my-codex

General

Q: Something is broken. What's the first thing to try?

omx doctor    # check config and dependencies
omx cleanup   # remove stale state and zombie processes

Q: Where do I report bugs? The project is hosted at github.com/Yeachan-Heo/oh-my-codex. File issues there with reproduction steps. Reference the GitHub issue numbers in this guide when they apply to your situation.

Q: The HUD shows stale data after a session ends. Run omx cleanup. The HUD reads from live state files; stale files produce stale display.

Q: Can I run omx in CI/CD? Team mode (which requires tmux and an interactive TTY) is difficult in most CI environments. Single-agent modes (omx explore, omx sparkshell, omx skill) may work in CI. Set OMX_RUNTIME_CLI_DISABLE_AUTO_START=true to prevent auto-start behaviors that assume an interactive session.

Q: How does omx prevent two workers from picking up the same job? Jobs are claimed via atomic file operations on the shared jobs directory. The worker renames the job file as a lock operation; only one worker can successfully complete the rename, preventing double-claim.

Q: Is there a way to see what commands are available without reading the docs?

omx --help
omx skill help
omx agents list
omx hooks list
omx adapt --help