Turn Codex CLI into a coordinated operating layer with autonomous research, orchestration wrappers, team worktrees, and intent-first deep interviews.
v0.17.0 adds the bounded Hermes MCP bridge, establishes the canonical $design workflow, exposes OMX skills in plugin-mode discovery, strengthens $ultraqa with adversarial e2e expectations, and hardens Windows hooks, tmux ownership, startup shell isolation, committed project memory, and Ultragoal reconciliation.
Specialized prompt catalog across build, review, domain, product, and coordination lanes.
Execution workflows spanning autopilot, review, orchestration, notifications, research, and recovery.
State, memory, code intelligence, team orchestration, and trace visibility wired into one operator surface.
Hermes MCP, canonical $design, plugin-mode skill discovery, adversarial UltraQA, runtime ownership hardening, and Ultragoal reconciliation.
Recent releases add Hermes MCP coordination, canonical design docs, plugin-mode discovery, adversarial QA, safer hooks, tmux ownership checks, and stricter Ultragoal completion proof.
$design workflow: DESIGN.md becomes the durable product/UI decision surface and mirrored skill guidance replaces the older frontend shortcut.$ultraqa now requires hostile scenario modeling, prompt-injection attempts, interrupt/cancel/resume coverage, stale-state checks, and cleanup evidence.Minor release. Published May 12, 2026.
Patch release. Published May 11, 2026.
omx question rendering: Fails closed outside attached tmux panes with a clear operator-facing error instead of spawning an unseen detached renderer.ㅕㅣㅈ on a Korean 2-set keyboard normalize to the ulw ultrawork shorthand before activation.buildSendPaneArgvs path as reply-listener pane injection.omx question terminals to finish and read the JSON answer before continuing.6.0.3, Biome lockfile metadata refreshed to 2.4.12, and tsconfig.json pins Node ambient types for the TS 6 build path.Patch release. Released April 21, 2026.
omx update can refresh setup state even when the installed version is already current; advisory update-state write failures no longer block the refresh path.Patch release. Released April 21, 2026.
npm audit fix patches transitive CVEs.omx explore fails closed on shell-startup re-entry and allowlist wrappers no longer self-resolve..omx-based project-root discovery, and AGENTS.md preservation during auto-update./skills without renaming, Shift+Enter tmux triage docs added.Patch release. Released April 18, 2026.
omx team status --json parseable.Patch release. Released April 7, 2026.
.codex/hooks.json.PreToolUse/PostToolUse guidance shipped and documented for destructive-command warnings and error guidance.docs/readme/ (15 languages).185 changed files, 65 non-merge commits, 26 merge commits. Released April 6, 2026.
Patch release. Released April 4, 2026.
omx autoresearch mode iteratively explores topics and self-terminates when the research goal is satisfied.omx exec runs commands through the OMX orchestration layer with full agent context.54 commits, 26 PRs, 105 files changed. Released March 15, 2026.
omx autoresearch mode iteratively explores topics and self-terminates when the research goal is satisfied.omx exec runs commands through the OMX orchestration layer with full agent context and coordination.54 commits, 26 PRs, 105 files changed, +7581/−388 lines. Released March 15, 2026.
omx explore as the default read-only exploration entrypoint with a constrained native harness and repository-safe allowlists.omx sparkshell for shell-native command execution, adaptive summaries, and tmux pane capture.omx resume as the direct terminal command for restoring an earlier interactive Codex session.omx-explore-harness and omx-sparkshell with manifest-based hydration.npm run build:full, npm run test:explore, npm run test:sparkshell, and packed-install smoke checks.configure-notifications skill.omx ask command for direct claude/gemini querying.deep-interview workflow with Socratic ambiguity gating.web-clone skill.ralph auto-run cleanup.pipeline orchestrator.uninstall command.--force now parses correctly from CLI arguments.shutdown_gate_forced audit event.scale_up and scale_down).workingDirectory, prevented path traversal, and blocked HUD escape injection.OMX_TEAM_WORKER_CLI_MAP for per-worker provider selection.omx ralph subcommand.--spark and --madmax-spark.These quick references cover the major operational surfaces added across v0.7 through v0.9, from scaling and consensus planning to native exploration and notification integrations.
scale_up / scale_down while a team is running.OMX_TEAM_SCALING_ENABLED=1.scale_down drains workers safely before removal, and scaling operations are lock-protected to prevent overlapping changes.$ralplan is shorthand for $plan --consensus.--deliberate for high-risk work (security, migrations, destructive operations, public API breakage).notifications.openclaw hooks or generic command/webhook aliases.OMX_OPENCLAW=1 to enable the dispatch path. For command gateways, also set OMX_OPENCLAW_COMMAND=1.session-start, session-idle, ask-user-question, session-stop, and session-end.Full guide: OpenClaw / Generic Notification Gateway Integration Guide.
Team workers now run in isolated git worktrees by default. The --worktree flag is deprecated and treated as a no-op — worktrees are always on.
omx team starts..omx/team/<name>/worktrees/worker-N.The integration engine selects the best strategy per worker automatically:
--no-ff -X theirs) — when the worker is cleanly ahead of the leader. Fast and conflict-free.Conflicts are detected early and logged to .omx/state/team/<team>/integration-report.md with per-file detail.
Workers must commit before reporting completion: git add -A && git commit -m "task: <subject>". The runtime auto-commits as a fallback if a worker forgets, but explicit commits are preferred for cleaner history.
# Worktrees are automatic — no flags needed
omx team 3:executor "implement feature X"
# Check worker worktree status
omx team status <team-name>
# Output includes: worktree_path, worktree_branch, worktree_detached per worker
# Mixed providers — all get worktrees
OMX_TEAM_WORKER_CLI_MAP=codex,claude,gemini omx team 3:executor "full-stack work"<leader-cwd>/.omx/state) and shared across all worktrees via OMX_TEAM_STATE_ROOT.worktree_path, worktree_branch, worktree_detached, and worktree_created for full observability.OMX_TEAM_WORKER_CLI_MAP=codex,claude,gemini.Run mixed teams with Gemini to leverage specialized reasoning strengths.
# 1. Start a mixed provider team
export OMX_TEAM_WORKER_CLI_MAP=codex,claude,gemini
omx team 3:executor "full-stack implementation"
# 2. Force all workers to Gemini
export OMX_TEAM_WORKER_CLI=gemini
omx team 2:architect "large-scale architectural review"
# 3. Pass explicit Gemini models
export OMX_TEAM_WORKER_LAUNCH_ARGS="--model gemini-2.0-flash-exp"
omx team 1:executor "experimental feature"Gemini worker behavior notes:
--approval-mode yolo -i "..." to ensure reliable tmux bring-up.# 1. Install globally
npm install -g oh-my-codex
# 2. Run setup
omx setup
# 3. Verify installation
omx doctorOMX uses "Magic Keywords" and $skill commands to detect your intent. Just describe what you want.
# Inside Codex CLI:
/prompts:architect "analyze current auth boundaries"
/prompts:executor "implement input validation in login"
$plan "ship OAuth callback safely"
$team 3:executor "fix all TypeScript errors"
# From terminal:
omx team 4:executor "parallelize a multi-module refactor"
omx team status <team-name>
omx team shutdown <team-name>"autopilot build a React dashboard" — Full autonomous execution from idea to code.
"ralph refactor the API" — Persists until verified clean ("The boulder never stops").
"ulw fix all errors" — Runs multiple agents in parallel for speed.
"team 5:executor refactor backend" — Spawns a team of 5 agents coordinated from the leader pane.
"plan the auth system" — Starts an interactive planning interview.
Codex CLI is strong for direct tasks. OMX adds structure for larger work:
team-plan → team-prd → team-exec → team-verify → team-fix pipeline..omx/state/ for resumable execution.The core principle of OMX is: You are the conductor, not the performer.
NEVER make code changes directly. ALWAYS delegate to specialized agents. Your role is to guide, review, and orchestrate.
Agents have specialized roles. The architect sees the big picture, the executor writes the code, and the verifier proves it works. Respecting this division ensures higher quality output.
OMX organizes 30+ specialized agents into functional lanes. Use /prompts:name to invoke them.
OMX uses a staged pipeline for teams in tmux. Transitions are strictly defined to ensure quality gates.
| From | To | Trigger Condition |
|---|---|---|
| team-plan | team-prd | Planning and decomposition complete |
| team-prd | team-exec | Acceptance criteria explicitly defined |
| team-exec | team-verify | All tasks reach terminal state |
| team-verify | team-fix / complete | Verification outcome |
| team-fix | team-exec / team-verify | Fix strategies defined |
OMX intelligently routes tasks to the most appropriate model tier to balance cost and capability.
| Complexity | Model | Use Case |
|---|---|---|
| Simple | Spark | Lookups, formatting, simple docs ("What does this return?") |
| Standard | Default | Implementation, tests, refactoring ("Add error handling") |
| Complex | xhigh reasoning | Architecture, deep debugging, planning ("Refactor auth system") |
.omx/, .codex/ config files.
The flagship mode. Full autonomous execution from idea to delivered code. Self-correcting loop.
"The boulder never stops." Persistence mode. Keeps working until the Architect verifies the goal is met.
Maximum parallelism. Aggressively delegates subtasks to multiple background agents.
All team compositions below run in isolated git worktrees by default. Each worker gets its own worktree automatically — zero merge conflicts, incremental integration, and clean shutdown rollback.
state_read, state_write, state_clear for managing execution mode state.notepad_read, notepad_write_priority, notepad_write_working, notepad_write_manual.LSP Tools: lsp_hover, lsp_goto_definition, lsp_find_references, lsp_diagnostics, lsp_rename.
AST Grep: ast_grep_search, ast_grep_replace for structural refactoring.
Python REPL: Persistent environment for data analysis.
By default, MCP state/memory/trace tools accept caller-provided workingDirectory. To constrain this, set an allowlist of roots:
export OMX_MCP_WORKDIR_ROOTS="/path/to/project:/path/to/another-root"When set, workingDirectory values outside these roots will be rejected by the tools for security.
| Keyword | Description | Example |
|---|---|---|
autopilot | Autonomous execution | "autopilot build a login page" |
ralph | Persistence mode | "ralph refactor the API" |
ulw | Ultrawork (Parallel) | "ulw fix these 5 bugs" |
$team | tmux Team workers | "$team 3:executor build it" |
plan | Strategic planning | "plan the migration" |
$ralplan | Consensus planning | "$ralplan the API" |
Skills are invoked with $name inside Codex CLI. Agent prompts are loaded with /prompts:name.
Utility Skills: $cancel, $note, $hud, $omc-doctor.
Located at .omx/notepad.md. Resilient memory surviving context pruning.
Located at .omx/project-memory.json. Stores tech stack, conventions, and architectural directives.
Run omx setup to configure defaults. Use --scope user or --scope project to control where files are installed.
Worktree Paths:
.omx/state/ - Mode state files.omx/logs/ - Audit logs.omx/plans/ - Planning documentsThe omx command-line tool lets you launch, configure, and manage OMX from your terminal.
Run these commands to install and start fast.
npm install -g oh-my-codexomx (launches Codex CLI with HUD in tmux)omx setupomx doctoromx resumenpm install -g oh-my-codex
omx
omx setup
omx doctor
omx resume
omx --xhigh --madmaxFor maximum power, run omx --xhigh --madmax.
| Command | What It Does |
|---|---|
omx | Launch Codex CLI (HUD auto-attaches in tmux) |
omx setup | Install skills, prompts, MCP servers, and AGENTS.md. Supports --scope user|project. |
omx agents-init . | Bootstrap lightweight AGENTS.md files for a repository or subtree. |
omx doctor | Check installation health. Use --team for worker diagnostics. |
omx ask <provider> | Directly query advisor (claude|gemini). Supports --agent-prompt <name>. |
omx resume | Resume a previous interactive Codex session from the terminal. |
omx explore | Default read-only exploration surface for shell-native repository inspection. May route through sparkshell when appropriate. |
omx sparkshell | Explicit shell-native inspection command with adaptive summaries and tmux pane capture support. |
omx team | Spawn/status/resume/shutdown parallel worker panes in tmux. |
omx ralph | Launch Codex with ralph persistence mode active. |
omx status | Show active modes and execution state. |
omx cancel | Cancel active execution modes (autopilot, team, etc.). |
omx hud | Inspect runtime HUD state with watch/json/preset-oriented operator views. |
omx reasoning [mode] | Show or set model reasoning effort (low|medium|high|xhigh). |
omx version | Show version information. |
omx help | Show the help message. |
| Flag | What It Does |
|---|---|
--yolo | Launch Codex in yolo mode. |
--high / --xhigh | Shorthand for high/extra-high reasoning effort. |
--madmax | DANGEROUS: bypass Codex approvals and sandbox. |
--spark | Use Codex spark model (~1.3x faster) for team workers. |
--madmax-spark | Spark model + bypass approvals for leader and workers. |
-w, --worktree[=<name>] | Launch in a git worktree (isolated environment). |
--force | Force reinstall (overwrite existing files) during setup. |
--dry-run | Show what would be done without doing it. |
--verbose | Show detailed output for debugging. |
--scope <user|project> | Control installation target (global or local). |
omx explore is intentionally read-only and shell-only. It is suited to quick repository discovery, while omx resume and omx sparkshell cover operator recovery and direct shell-native inspection.
# Read-only repository exploration
omx explore --prompt "which files define team routing"
omx explore --prompt-file prompts/explore-task.md
# Resume interactive work
omx resume
# Direct sparkshell inspection
omx sparkshell git --version
omx sparkshell --tmux-pane %12 --tail-lines 400omx explore does not promise full Codex tool parity. It stays read-only, shell-only, and blocks pipes, redirection, shell chaining, and path escapes outside the target repository.
omx explore currently allowlists rg, grep, ls, find, wc, cat, head, tail, pwd, and printf.omx sparkshell uses env-based model routing such as OMX_SPARKSHELL_MODEL and supports explicit tmux-pane summarization when requested.The omx ask command allows you to query specialized advisors directly from your terminal.
# Simple queries
omx ask claude "review this diff"
omx ask gemini "brainstorm alternatives for the auth system"
# Role-specific queries
omx ask claude --agent-prompt executor "implement feature X with tests"
omx ask gemini --agent-prompt planner "draft a rollout plan for v0.9"
# Shorthand prompt flags
omx ask claude -p "summarize the recent changes"
omx ask gemini --prompt "check this regex for errors"| Command | What It Does |
|---|---|
omx team 3:executor "task" | Start team workers on a task |
omx team 2:explore "short scoped analysis task" | Launch a small read-only exploration team for fast repository analysis. |
omx team status <team-name> | Check team status |
omx team resume <team-name> | Resume team |
omx team shutdown <team-name> [--force] | Shutdown team |
| Env vars | OMX_TEAM_WORKER_CLI (auto|codex|claude|gemini), OMX_TEAM_WORKER_CLI_MAP (per-worker mix like codex,claude,gemini) |
OMX also exposes hook scaffolding, HUD inspection, and native build or verification helpers for autoresearch, exec, and team worktree surfaces.
| Command | Description |
|---|---|
omx hooks init | Scaffold a new hook plugin in .omx/hooks/. |
omx hooks status | Show status of installed hook plugins. |
omx hooks validate | Validate hook plugin implementation. |
omx hud --watch | Watch runtime state and HUD output live. |
omx hud --json | Emit HUD status as machine-readable JSON. |
omx tmux-hook init | Initialize tmux prompt injection workaround. |
npm run build:full | One-shot TypeScript plus packaged native build for explore harness and sparkshell. |
npm run test:explore | Verify the native exploration harness and integration path. |
npm run test:sparkshell | Verify sparkshell behavior, summaries, and native bridge wiring. |
Plugins are disabled by default. Enable them by setting OMX_HOOK_PLUGINS=1 in your environment.
Get alerts when your OMX session changes state or needs your input.
config.toml or with environment variables.Start with environment variables, then run omx setup to write a config file.
The fastest setup is exporting env vars, then running setup.
export OMX_TELEGRAM_BOT_TOKEN=xxx
export OMX_TELEGRAM_CHAT_ID=xxx
export OMX_DISCORD_WEBHOOK_URL=xxx
export OMX_SLACK_WEBHOOK_URL=xxx
omx setupOMX supports multiple platforms to ensure you stay informed wherever you work.
| Platform | Key Config Fields | Details |
|---|---|---|
| Telegram | botToken, chatId |
Supports parseMode (Markdown or HTML). Responds to authorized chat IDs for reply injection. |
| Discord (Webhook) | webhookUrl |
Simple one-way alerts. Supports custom username and mention target (e.g. <@123456>). |
| Discord (Bot API) | botToken, channelId |
Recommended for two-way communication. Requires a Discord bot with Send Messages permissions. |
| Slack | webhookUrl |
Supports custom channel, username, and mention target (e.g. <!here>). |
| Generic Webhook | url |
POST or PUT JSON payloads to any endpoint. Supports custom headers for auth. |
| OpenClaw | openclaw: { enabled: true } |
Advanced gateway for programmable hook orchestration. See OpenClaw Configuration. |
OpenClaw is the recommended path for production-grade notification orchestration. It allows you to trigger agent turns and complex follow-up behaviors.
{
"notifications": {
"verbosity": "verbose",
"openclaw": {
"enabled": true,
"gateways": {
"local": {
"type": "http",
"url": "http://127.0.0.1:18789/hooks/agent",
"headers": { "Authorization": "Bearer ${HOOKS_TOKEN}" }
}
},
"hooks": {
"session-start": {
"enabled": true,
"gateway": "local",
"instruction": "[session-start|exec] project={{projectName}} session={{sessionId}}"
},
"ask-user-question": {
"enabled": true,
"gateway": "local",
"instruction": "[ask-user-question|exec] session={{sessionId}} question={{question}}"
}
}
}
}
}For more details, see the Full OpenClaw Integration Guide.
| Event | When It Fires |
|---|---|
session-start | Fires when Codex session starts. |
session-stop | Fires when session stops (mode complete or user interrupt). |
session-end | Fires when session exits. |
session-idle | Fires when session is idle (waiting for input). |
ask-user-question | Fires when agent asks user a question. |
| Level | Behavior |
|---|---|
verbose | All text and tool call output. |
agent | Per-agent-call events (includes ask-user-question). |
session | Start, idle, stop, and end events plus tmux tail snippet (default). |
minimal | Start, stop, and end only. No idle, no tmux tail. |
| Variable | Purpose |
|---|---|
OMX_DISCORD_WEBHOOK_URL | Discord webhook endpoint. |
OMX_DISCORD_NOTIFIER_BOT_TOKEN | Discord bot token for Bot API mode. |
OMX_DISCORD_NOTIFIER_CHANNEL | Discord channel ID for Bot API mode. |
OMX_DISCORD_MENTION | Optional mention target for Discord notifications. |
OMX_TELEGRAM_BOT_TOKEN | Telegram bot token. |
OMX_TELEGRAM_CHAT_ID | Telegram chat ID. |
OMX_SLACK_WEBHOOK_URL | Slack webhook endpoint. |
OMX_SLACK_MENTION | Optional mention target for Slack notifications. |
{{variable}} syntax.event, sessionId, timestamp, projectName, activeMode, question, tmuxTail.Configurations are stored in ~/.codex/config.toml (Codex native) or .omx-config.json (OMX advanced).
[notifications]
enabled = true
verbosity = "session"
[notifications.telegram]
enabled = true
botToken = "123456:ABC-DEF"
chatId = "-100123456789"
[notifications.slack]
enabled = true
webhookUrl = "https://hooks.slack.com/services/xxx"
mention = "@U12345"For more advanced routing, you can use generic command or webhook aliases:
{
"notifications": {
"custom_webhook_command": {
"enabled": true,
"url": "https://api.example.com/hooks",
"method": "POST",
"headers": { "X-Api-Key": "my-secret-key" },
"events": ["session-end", "ask-user-question"]
},
"custom_cli_command": {
"enabled": true,
"command": "notify-send \"OMX: {{event}}\" \"{{message}}\"",
"events": ["session-start", "session-end"]
}
}
}You can fine-tune team behavior using environment variables or .omx-config.json.
# Mix different AI providers in one team
export OMX_TEAM_WORKER_CLI_MAP=codex,claude,gemini
omx team 3:executor "parallel refactoring"
# Force all workers to Gemini CLI
export OMX_TEAM_WORKER_CLI=gemini
omx team 2:executor "sync docs and report"
# Force a specific model for workers
export OMX_TEAM_WORKER_LAUNCH_ARGS="--model gpt-5.3-codex-spark"
omx team 2:architect "design the system"
# Enable dynamic scaling
export OMX_TEAM_SCALING_ENABLED=1
omx team 2:executor "task"enabled, pollIntervalMs, maxMessageLength, and rateLimitPerMinute.Battle-tested patterns for common tasks. Pick the one that fits.
For big features that need a plan first.
When the task is clear and you just want it done.
For bugs and errors.
For handling multiple issues or tickets at the same time.
These four patterns cover most real-world work. Other skills exist for specific tasks, but you rarely need them day-to-day.
For large-scale engineering, OMX supports complex team configurations, mixed CLI workers, and git worktree isolation.
You can mix different AI providers (Codex, Claude, and Gemini) within a single team to leverage their unique strengths.
# Mix Codex, Gemini, and Claude workers in one team
export OMX_TEAM_WORKER_CLI_MAP=codex,gemini,claude
omx team 3:executor "refactor the shared runtime docs"All mutations and coordination should use the CLI interop API for stable JSON-based state transitions. This is critical for automated tooling and complex worker coordination.
# Create a task programmatically
omx team api create-task --input '{"team_name":"my-team","subject":"Fix bug","description":"..."}' --json
# Claim a task with versioned safety
omx team api claim-task --input '{"team_name":"my-team","task_id":"1","worker":"worker-1"}' --json
# Transition terminal task status after claiming
omx team api transition-task-status --input '{"team_name":"my-team","task_id":"1","from":"in_progress","to":"completed","claim_token":""}' --json Launch teams in dedicated git worktrees to prevent parallel workers from clobbering each other's files. OMX handles state resolution across these worktrees automatically.
# Launch in a new worktree
omx team 4:executor "feature work" --worktree=feature-branchOMX maintains a durable, claim-safe lifecycle for every task. If a worker fails or a session is interrupted, the state is preserved in .omx/state/team/, allowing for safe resumes with omx team resume <team-name>.