Oh My Codex Documentation

Turn Codex CLI into a coordinated operating layer with autonomous research, orchestration wrappers, team worktrees, and intent-first deep interviews.

v0.10.0 adds autonomous research with omx autoresearch, an orchestration wrapper via omx exec, default team worktrees for isolated parallel work, intent-first deep interviews, and incremental worktree merge tracking.

Autonomous research Orchestration wrapper Team worktrees Intent-first interviews

33 Agent Prompts

Specialized prompt catalog across build, review, domain, product, and coordination lanes.

36 Skills

Execution workflows spanning autopilot, review, orchestration, notifications, research, and recovery.

5 MCP Servers

State, memory, code intelligence, team orchestration, and trace visibility wired into one operator surface.

v0.10.0 Highlights

omx autoresearch, omx exec, default team worktrees, intent-first deep interviews, and incremental merge tracking.

#Release Notes

Quick Summary

Recent releases sharpen the operator loop: autonomous research, orchestration wrappers, default team worktrees, intent-first deep interviews, and incremental merge tracking.

v0.10.0 Autonomous Research & Team Worktrees
View changes in v0.10.0
  • Autoresearch: New omx autoresearch mode iteratively explores topics and self-terminates when the research goal is satisfied.
  • Exec wrapper: omx exec runs commands through the OMX orchestration layer with full agent context and coordination.
  • Team worktrees: Team workers now get isolated git worktrees by default, enabling conflict-free parallel execution.
  • Deep-interview intent-first: Intent classification happens upfront before the Socratic interview loop, improving question targeting.
  • Incremental merge tracking: Smarter conflict detection across worktrees with incremental diff-based merge awareness.

54 commits, 26 PRs, 105 files changed, +7581/−388 lines. Released March 15, 2026.

v0.9.0 Spark Initiative
View changes in v0.9.0
  • CLI: Added omx explore as the default read-only exploration entrypoint with a constrained native harness and repository-safe allowlists.
  • Inspection: Added omx sparkshell for shell-native command execution, adaptive summaries, and tmux pane capture.
  • Recovery: Added omx resume as the direct terminal command for restoring an earlier interactive Codex session.
  • Releases: Tagged releases now ship native archives for omx-explore-harness and omx-sparkshell with manifest-based hydration.
  • Verification: Release lanes now cover npm run build:full, npm run test:explore, npm run test:sparkshell, and packed-install smoke checks.
v0.8.1 Team CLI Interop API
View changes in v0.8.1
  • API: Added Team CLI interop API for specialized worker coordination.
  • Config: Unified configure-notifications skill.
v0.8.0 Model Ask and Socratic Interview
View changes in v0.8.0
  • CLI: Added omx ask command for direct claude/gemini querying.
  • Workflow: Added deep-interview workflow with Socratic ambiguity gating.
  • Skills: Added web-clone skill.
v0.7.6 Hotfix
View changes in v0.7.6
  • Fix: Hotfix after 0.7.5 release.
v0.7.5 Ralph Cleanup and Worker Routing
View changes in v0.7.5
  • Refactor: 26 commits including ralph auto-run cleanup.
  • Mode: Added tmux session mode.
  • Routing: Added per-worker role routing.
  • Fix: OpenClaw notification fixes.
v0.7.3 Pipeline Orchestrator
View changes in v0.7.3
  • Skill: Added pipeline orchestrator.
  • CLI: Added uninstall command.
  • Core: Team dispatch hardening.
v0.7.2 Team Shutdown Force Flag (Hotfix)
View changes in v0.7.2
  • Fix: Team shutdown --force now parses correctly from CLI arguments.
  • Audit: Added the shutdown_gate_forced audit event.
v0.7.0 Major Release (153 files changed)
View changes in v0.7.0
  • Scaling: Added dynamic team worker scaling (Phase 1 manual scale_up and scale_down).
  • Planning: Added RALPLAN-DR structured deliberation for consensus planning.
  • Scoping: Added a task-size detector for pre-execution guidance.
  • Triggers: Added a keyword trigger registry with 31 keyword triggers.
  • Notifications: Overhauled notifications across Slack, Discord, and Telegram.
  • Integration: Added OpenClaw gateway integration.
  • CLI: Added the star-prompt command.
  • Setup: Simplified setup from 3 scopes to 2 scopes (user and project).
  • MCP: Added an MCP bootstrap module.
  • HUD: Added watch render serialization, quota rendering, and session duration improvements.
  • Tests: Reached 1,472 tests across 308 suites.
  • Security: Hardened MCP workingDirectory, prevented path traversal, and blocked HUD escape injection.
v0.6.x Mixed Team Workers and Reliability
View changes in v0.6.x
  • Routing: Added mixed team worker CLI routing via OMX_TEAM_WORKER_CLI_MAP for per-worker provider selection.
  • Fallback: Added leader-side all-workers-idle nudge fallback.
  • Reliability: Added an adaptive trigger submit retry guard.
  • Startup: Fixed team Claude worker startup issues.
  • HUD: Added a HUD reconcile hook for detached launches.
v0.5.x Worktree and Ralph CLI
View changes in v0.5.x
  • Worktrees: Added native worktree orchestration for team mode.
  • State: Added cross-worktree team state resolution.
  • CLI: Added the omx ralph subcommand.
  • Persistence: Added scoped ralph state with canonical persistence migration.
  • Interop: Added a claim-safe team transition tool for MCP interop.
  • Notifications: Cleaned tmux pane output for notifications.
  • Startup: Added a startup codebase map injection hook.
  • Security: Added command injection prevention and path traversal prevention.
v0.5.0 Catalog Consolidation
View changes in v0.5.0
  • Setup: Added scope-aware setup (user and project).
  • Routing: Added Spark worker routing via --spark and --madmax-spark.
  • Cleanup: Consolidated the catalog by removing deprecated prompts and 9 skills.
  • Logging: Added notifier verbosity levels.
v0.4.x Hook Extensibility and Auto-nudge
View changes in v0.4.x
  • Hooks: Added hook extensibility runtime with CLI integration.
  • Detection: Expanded auto-nudge stall detection patterns.
  • Notifications: Added worker-idle aggregation notifications.
  • Tmux: Enabled automatic tmux mouse scrolling for team sessions.
  • Agents: Registered OMX agents as Codex native multi-agent roles.

#Feature Guides

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.

#Dynamic Team Worker Scaling

  • Phase 1 supports manual scale_up / scale_down while a team is running.
  • Enable scaling with OMX_TEAM_SCALING_ENABLED=1.
  • scale_down drains workers safely before removal, and scaling operations are lock-protected to prevent overlapping changes.

#RALPLAN-DR Consensus Planning

  • $ralplan is shorthand for $plan --consensus.
  • Workflow uses Planner → Architect → Critic with a structured RALPLAN-DR summary before execution.
  • Default mode is short consensus; use --deliberate for high-risk work (security, migrations, destructive operations, public API breakage).

#OpenClaw Integration

  • OpenClaw can be configured with explicit notifications.openclaw hooks or generic command/webhook aliases.
  • Set OMX_OPENCLAW=1 to enable the dispatch path. For command gateways, also set OMX_OPENCLAW_COMMAND=1.
  • Common hook events: session-start, session-idle, ask-user-question, session-stop, and session-end.

Full guide: OpenClaw / Generic Notification Gateway Integration Guide.

#Worktree Orchestration (Default in v0.10.0)

Game-changer in v0.10.0

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.

How It Works

  1. Clean leader workspace required — leader must have a committed/stashed workspace before omx team starts.
  2. Automatic worktree provisioning — each worker gets a detached worktree at .omx/team/<name>/worktrees/worker-N.
  3. Workers commit to their worktree — isolated branches mean zero write conflicts between workers.
  4. Leader merges incrementally — the runtime continuously integrates worker commits back into the leader branch.
  5. Shutdown cleanup — provisioned worktrees are rolled back and branches deleted on team shutdown.

Incremental Merge Strategies

The integration engine selects the best strategy per worker automatically:

  • Merge (--no-ff -X theirs) — when the worker is cleanly ahead of the leader. Fast and conflict-free.
  • Cherry-pick — when histories have diverged. Picks individual worker commits into the leader branch.
  • Cross-worker rebase — for sequential dependencies between workers. Rebases one worker's branch onto another's integrated state.

Conflicts are detected early and logged to .omx/state/team/<team>/integration-report.md with per-file detail.

Worker Commit Protocol

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.

BASH
# 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"

Cross-Worktree State Resolution

  • Team state root is resolved from the leader cwd (<leader-cwd>/.omx/state) and shared across all worktrees via OMX_TEAM_STATE_ROOT.
  • Dispatch, task claims, mailbox delivery, and lifecycle updates remain consistent across all worker worktrees.
  • Worker identity files track worktree_path, worktree_branch, worktree_detached, and worktree_created for full observability.

#Gemini-Powered Teams

  • Full support for Gemini CLI workers in OMX Team mode.
  • Leverage Gemini's massive context window and reasoning capabilities for complex architectural planning and codebase-wide refactors.
  • Mixed-provider teams (Codex + Claude + Gemini) enable the ultimate "best-of-breed" orchestration.
  • Configure with OMX_TEAM_WORKER_CLI_MAP=codex,claude,gemini.

Runtime Examples

Run mixed teams with Gemini to leverage specialized reasoning strengths.

BASH
# 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:

  • Prompt-interactive startup: Gemini workers are automatically seeded with an initial prompt using --approval-mode yolo -i "..." to ensure reliable tmux bring-up.
  • Model Filtering: Non-Gemini default models (like Spark) are automatically filtered out when launching Gemini workers to prevent provider/model mismatches.
  • Context Advantage: Use Gemini workers for tasks requiring deep codebase context or long-form architectural synthesis.

#Installation

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

# 2. Run setup
omx setup

# 3. Verify installation
omx doctor

#Quick Start

OMX uses "Magic Keywords" and $skill commands to detect your intent. Just describe what you want.

EXAMPLES
# 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>

  • Autonomous Building

    "autopilot build a React dashboard" — Full autonomous execution from idea to code.

  • Refactoring

    "ralph refactor the API" — Persists until verified clean ("The boulder never stops").

  • Parallel Work

    "ulw fix all errors" — Runs multiple agents in parallel for speed.

  • tmux Teams

    "team 5:executor refactor backend" — Spawns a team of 5 agents coordinated from the leader pane.

  • Planning

    "plan the auth system" — Starts an interactive planning interview.

#Why OMX

Codex CLI is strong for direct tasks. OMX adds structure for larger work:

  • Decomposition and staged execution: Managed through team-plan → team-prd → team-exec → team-verify → team-fix pipeline.
  • Persistent mode lifecycle state: Stored in .omx/state/ for resumable execution.
  • Memory + notepad surfaces: Dedicated workspace for long-running sessions.
  • Operational controls: Fine-grained control over launch, verification, and cancellation.

#Conductor Philosophy

The core principle of OMX is: You are the conductor, not the performer.

Golden Rule

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.

#Agent Tiers & Catalog

OMX organizes 30+ specialized agents into functional lanes. Use /prompts:name to invoke them.

Build & Analysis

Implementation Core

explore Search planner Sequence architect Design executor Code debugger Fix verifier Evidence
Review Lane

Quality Gates

code-reviewer security-reviewer performance-reviewer api-reviewer style-reviewer
Domain Specialists

Deep Expertise

dependency-expert test-engineer git-master designer researcher
Product & Coordination

Strategy & Feedback

product-manager ux-researcher critic Challenge vision Images

#Team Architecture

OMX uses a staged pipeline for teams in tmux. Transitions are strictly defined to ensure quality gates.

1
team-plan
→
2
team-prd
→
3
team-exec
→
4
team-verify
→
5
team-fix
FromToTrigger Condition
team-planteam-prdPlanning and decomposition complete
team-prdteam-execAcceptance criteria explicitly defined
team-execteam-verifyAll tasks reach terminal state
team-verifyteam-fix / completeVerification outcome
team-fixteam-exec / team-verifyFix strategies defined

#Model Routing

OMX intelligently routes tasks to the most appropriate model tier to balance cost and capability.

ComplexityModelUse Case
SimpleSparkLookups, formatting, simple docs ("What does this return?")
StandardDefaultImplementation, tests, refactoring ("Add error handling")
Complexxhigh reasoningArchitecture, deep debugging, planning ("Refactor auth system")

#Delegation Rules

  • ✅ Delegate: Multi-file implementations, refactors, debugging, reviews, planning, research, verification.
  • 🛑 Do It Yourself: Small clarifications, quick status checks, single-command operations. Direct writes are OK for .omx/, .codex/ config files.

#Execution Modes

🤖

Autopilot

autopilot

The flagship mode. Full autonomous execution from idea to delivered code. Self-correcting loop.

  • Expansion (Analyst + Architect)
  • Planning (Architect + Critic)
  • Execution (Ralph + Ultrawork)
  • QA Cycling (UltraQA)
🔄

Ralph

ralph

"The boulder never stops." Persistence mode. Keeps working until the Architect verifies the goal is met.

  • Infinite persistence loop
  • Includes Ultrawork automatically
  • Strong verification requirements
⚡

Ultrawork

ulw

Maximum parallelism. Aggressively delegates subtasks to multiple background agents.

#Team Compositions

v0.10.0

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.

Feature Dev: analyst → planner → executor → test-engineer → verifier
Bug Fix: explore → debugger → executor → verifier

#MCP Tools

State & Runtime

Code Intelligence

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.

Utilities

Python REPL: Persistent environment for data analysis.

MCP workingDirectory policy (optional hardening)

By default, MCP state/memory/trace tools accept caller-provided workingDirectory. To constrain this, set an allowlist of roots:

BASH
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.

#Skills & Commands

KeywordDescriptionExample
autopilotAutonomous execution"autopilot build a login page"
ralphPersistence mode"ralph refactor the API"
ulwUltrawork (Parallel)"ulw fix these 5 bugs"
$teamtmux Team workers"$team 3:executor build it"
planStrategic planning"plan the migration"
$ralplanConsensus 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.

#State & Memory

Notepad System

Located at .omx/notepad.md. Resilient memory surviving context pruning.

Project Memory

Located at .omx/project-memory.json. Stores tech stack, conventions, and architectural directives.

#Configuration

Run omx setup to configure defaults. Use --scope user or --scope project to control where files are installed.

Worktree Paths:

#CLI Reference

The omx command-line tool lets you launch, configure, and manage OMX from your terminal.

Getting Started

Run these commands to install and start fast.

BASH
npm install -g oh-my-codex
omx
omx setup
omx doctor
omx resume
omx --xhigh --madmax
Tip

For maximum power, run omx --xhigh --madmax.

Core Commands

Command What It Does
omxLaunch Codex CLI (HUD auto-attaches in tmux)
omx setupInstall 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 doctorCheck installation health. Use --team for worker diagnostics.
omx ask <provider>Directly query advisor (claude|gemini). Supports --agent-prompt <name>.
omx resumeResume a previous interactive Codex session from the terminal.
omx exploreDefault read-only exploration surface for shell-native repository inspection. May route through sparkshell when appropriate.
omx sparkshellExplicit shell-native inspection command with adaptive summaries and tmux pane capture support.
omx teamSpawn/status/resume/shutdown parallel worker panes in tmux.
omx ralphLaunch Codex with ralph persistence mode active.
omx statusShow active modes and execution state.
omx cancelCancel active execution modes (autopilot, team, etc.).
omx hudInspect runtime HUD state with watch/json/preset-oriented operator views.
omx reasoning [mode]Show or set model reasoning effort (low|medium|high|xhigh).
omx versionShow version information.
omx helpShow the help message.

Launch Flags

Flag What It Does
--yoloLaunch Codex in yolo mode.
--high / --xhighShorthand for high/extra-high reasoning effort.
--madmaxDANGEROUS: bypass Codex approvals and sandbox.
--sparkUse Codex spark model (~1.3x faster) for team workers.
--madmax-sparkSpark model + bypass approvals for leader and workers.
-w, --worktree[=<name>]Launch in a git worktree (isolated environment).
--forceForce reinstall (overwrite existing files) during setup.
--dry-runShow what would be done without doing it.
--verboseShow detailed output for debugging.
--scope <user|project>Control installation target (global or local).

Explore, Sparkshell, and Resume

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.

BASH
# 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 400
Explore constraints

omx 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.

Advisor (Ask) Examples

The omx ask command allows you to query specialized advisors directly from your terminal.

BASH
# 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"

Team Commands

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 varsOMX_TEAM_WORKER_CLI (auto|codex|claude|gemini), OMX_TEAM_WORKER_CLI_MAP (per-worker mix like codex,claude,gemini)

Hooks, Extensions, and Native Build Helpers

OMX also exposes hook scaffolding, HUD inspection, and native build or verification helpers for autoresearch, exec, and team worktree surfaces.

Command Description
omx hooks initScaffold a new hook plugin in .omx/hooks/.
omx hooks statusShow status of installed hook plugins.
omx hooks validateValidate hook plugin implementation.
omx hud --watchWatch runtime state and HUD output live.
omx hud --jsonEmit HUD status as machine-readable JSON.
omx tmux-hook initInitialize tmux prompt injection workaround.
npm run build:fullOne-shot TypeScript plus packaged native build for explore harness and sparkshell.
npm run test:exploreVerify the native exploration harness and integration path.
npm run test:sparkshellVerify sparkshell behavior, summaries, and native bridge wiring.

Plugins are disabled by default. Enable them by setting OMX_HOOK_PLUGINS=1 in your environment.

#Notifications

Get alerts when your OMX session changes state or needs your input.

Overview

Tip

Start with environment variables, then run omx setup to write a config file.

Quick Setup

The fastest setup is exporting env vars, then running setup.

BASH
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 setup

Platforms

OMX 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 Configuration

OpenClaw is the recommended path for production-grade notification orchestration. It allows you to trigger agent turns and complex follow-up behaviors.

JSON (openclaw profile)
{
  "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.

Events

Event When It Fires
session-startFires when Codex session starts.
session-stopFires when session stops (mode complete or user interrupt).
session-endFires when session exits.
session-idleFires when session is idle (waiting for input).
ask-user-questionFires when agent asks user a question.

Verbosity

Level Behavior
verboseAll text and tool call output.
agentPer-agent-call events (includes ask-user-question).
sessionStart, idle, stop, and end events plus tmux tail snippet (default).
minimalStart, stop, and end only. No idle, no tmux tail.

Environment Variables

Variable Purpose
OMX_DISCORD_WEBHOOK_URLDiscord webhook endpoint.
OMX_DISCORD_NOTIFIER_BOT_TOKENDiscord bot token for Bot API mode.
OMX_DISCORD_NOTIFIER_CHANNELDiscord channel ID for Bot API mode.
OMX_DISCORD_MENTIONOptional mention target for Discord notifications.
OMX_TELEGRAM_BOT_TOKENTelegram bot token.
OMX_TELEGRAM_CHAT_IDTelegram chat ID.
OMX_SLACK_WEBHOOK_URLSlack webhook endpoint.
OMX_SLACK_MENTIONOptional mention target for Slack notifications.

Templates

Example Configuration

Configurations are stored in ~/.codex/config.toml (Codex native) or .omx-config.json (OMX advanced).

TOML (Codex Native)
[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:

JSON (.omx-config.json)
{
  "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"]
    }
  }
}

Advanced Team Configuration

You can fine-tune team behavior using environment variables or .omx-config.json.

BASH
# 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"

Reply Injection

#Recommended Workflows

Battle-tested patterns for common tasks. Pick the one that fits.

Full-Auto from PRD

For big features that need a plan first.

$ralplan → $team → $ralph
  1. $ralplan gathers requirements and creates a plan with planner + architect + critic consensus.
  2. $team spawns parallel tmux workers to build in parallel.
  3. $ralph persists until everything is verified complete.

No-Brainer

When the task is clear and you just want it done.

$autopilot → $ultrawork → $ralph
  1. $autopilot takes the wheel and runs autonomously.
  2. $ultrawork parallelizes subtasks for speed.
  3. $ralph persists until verified ("The boulder never stops").

Fix / Debugging

For bugs and errors.

$plan → $ralph → $ultraqa
  1. $plan investigates the problem and creates a fix strategy.
  2. $ralph implements fixes and keeps going until done.
  3. $ultraqa cycles through test -> verify -> fix until all tests pass.

Parallel Issue Handling

For handling multiple issues or tickets at the same time.

omx team (architect) → omx team (workers) → $ralplan → $ralph + $ultrawork → $ultraqa
  1. Start architect workers to analyze all issues and draft one complete plan.
  2. Run workers in parallel on separate worktrees, each submitting a PR to dev.
  3. Review and merge open PRs, then run $ralplan to resolve conflicts safely.
  4. Finish with $ralph, $ultrawork, and $ultraqa until all tests pass.
Good to know

These four patterns cover most real-world work. Other skills exist for specific tasks, but you rarely need them day-to-day.

#Advanced Orchestration

For large-scale engineering, OMX supports complex team configurations, mixed CLI workers, and git worktree isolation.

Mixed CLI Teams

You can mix different AI providers (Codex, Claude, and Gemini) within a single team to leverage their unique strengths.

BASH
# 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"

Team CLI API

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.

BASH
# 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

Worktree Isolation

Launch teams in dedicated git worktrees to prevent parallel workers from clobbering each other's files. OMX handles state resolution across these worktrees automatically.

BASH
# Launch in a new worktree
omx team 4:executor "feature work" --worktree=feature-branch
Architecture Insight

OMX 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>.