Oh My Codex

https://oh-my-codex.dev
Admin
Oh My Codex is a multi-agent orchestration layer for OpenAI Codex CLI that enables autonomous...
Tokens:9,803
Snippets:186
Trust Score:1.9
Update:5 months ago
Show doc for...
Tokens:
Raw
### Setup and Verify oh-my-codex Installation

Source: https://oh-my-codex.dev/index.html

After installation, run the setup command and then verify the installation with the doctor command. This ensures the environment is correctly configured.

```bash
omx setup && omx doctor
```

--------------------------------

### Install and Set Up Oh My Codex

Source: https://oh-my-codex.dev/docs.html

Install the Oh My Codex CLI globally using npm and run the setup command. Verify the installation by running the doctor command.

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

# 2. Run setup
omx setup

# 3. Verify installation
omx doctor
```

--------------------------------

### Quick Setup for Notifications

Source: https://oh-my-codex.dev/docs.html

Export environment variables for notification services and run `omx setup` to configure them. This is the fastest way to set up notifications.

```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
```

--------------------------------

### Explore, Sparkshell, and Resume Examples

Source: https://oh-my-codex.dev/docs.html

Examples demonstrating how to use `omx explore` for read-only repository discovery, `omx resume` to recover interactive sessions, and `omx sparkshell` for direct shell-native inspection with options for tmux pane summarization.

```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
```

--------------------------------

### Oh My Codex Advisor (Ask) Examples

Source: https://oh-my-codex.dev/docs.html

Examples of using the `omx ask` command to query specialized advisors like Claude or Gemini directly from the terminal. Includes examples for simple queries, role-specific prompts, and shorthand prompt flags.

```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"
```

--------------------------------

### Install oh-my-codex via npm

Source: https://oh-my-codex.dev/index.html

Install the oh-my-codex package globally using npm. This is the first step to get started with the tool.

```bash
npm install -g @openai/codex oh-my-codex
```

--------------------------------

### Install and Launch Oh My Codex

Source: https://oh-my-codex.dev/docs.html

Run these commands to install the Oh My Codex CLI globally and launch it. The `omx` command launches the CLI with a HUD in tmux by default.

```bash
npm install -g oh-my-codex
omx
omx setup
omx doctor
omx resume
omx --xhigh --madmax
```

--------------------------------

### Setup and Execute Codex CLI Commands

Source: https://oh-my-codex.dev/docs.html

Basic commands for setting up native hooks, executing parallel tasks within a team, and initiating a deep interview for feature ideas.

```bash
omx setup          # refreshes native hook wiring
```

```bash
omx team 3:executor "parallel task"
```

```bash
omx deep-interview "feature idea"
```

--------------------------------

### Oh My Codex Team Commands

Source: https://oh-my-codex.dev/docs.html

Examples and reference for managing teams of workers using `omx team`. This includes starting tasks, launching exploration teams, checking status, resuming, and shutting down teams, along with environment variables for worker configuration.

```bash
omx team 3:executor "task"
omx team 2:explore "short scoped analysis task"
omx team status <team-name>
omx team resume <team-name>
omx team shutdown <team-name> [--force]
```

--------------------------------

### Quick Start with OMX Magic Keywords and Skills

Source: https://oh-my-codex.dev/docs.html

Utilize magic keywords and $skill commands within the Codex CLI or from the terminal to initiate tasks, manage teams, and perform actions like planning or refactoring.

```bash
# 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>
```

--------------------------------

### Launch Interactive Codex Session

Source: https://oh-my-codex.dev/index.html

Start an interactive Codex session with recommended settings for trusted environments. Use `--madmax` and `--high` for granular control over reasoning effort and execution intensity.

```bash
# 1. Launch interactive Codex session
$ omx --madmax --high
```

--------------------------------

### Show Hook Plugin Status

Source: https://oh-my-codex.dev/docs.html

Show the status of installed hook plugins. This command helps in checking the current state of your hook plugins.

```bash
omx hooks status
```

--------------------------------

### Mixed Providers with Worktrees using $team

Source: https://oh-my-codex.dev/index.html

Configure mixed provider teams (Codex, Claude, Gemini) by setting the `OMX_TEAM_WORKER_CLI_MAP` environment variable. Each worker gets its own worktree.

```bash
# Mixed providers with worktrees
OMX_TEAM_WORKER_CLI_MAP=codex,claude,gemini \
  omx team 3:executor "full-stack implementation"
```

--------------------------------

### Scaffold New Hook Plugin

Source: https://oh-my-codex.dev/docs.html

Scaffold a new hook plugin in the `.omx/hooks/` directory. This command is used to start developing new hook plugins.

```bash
omx hooks init
```

--------------------------------

### Build and Test Commands

Source: https://oh-my-codex.dev/docs.html

Commands for building TypeScript and native components, and for verifying the exploration harness and sparkshell.

```bash
npm run build:full
```

```bash
npm run test:explore
```

```bash
npm run test:sparkshell
```

--------------------------------

### Configure and Run Mixed Provider Teams

Source: https://oh-my-codex.dev/docs.html

Set up and execute teams with multiple AI providers like Codex, Claude, and Gemini. Environment variables control the mix of providers and specific model arguments.

```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"
```

--------------------------------

### Launch oh-my-codex with High Intensity

Source: https://oh-my-codex.dev/index.html

Launch the tool with specific profiles for controlling reasoning effort and execution intensity. `--madmax --high` are recommended for trusted environments.

```bash
omx --madmax --high
```

--------------------------------

### Set Working Directory Roots for MCP Tools

Source: https://oh-my-codex.dev/docs.html

Configure security by setting an allowlist of root directories for MCP working directory tools. Values outside these roots will be rejected.

```bash
export OMX_MCP_WORKDIR_ROOTS="/path/to/project:/path/to/another-root"
```

--------------------------------

### Use Keywords Inside Codex for Workflows

Source: https://oh-my-codex.dev/index.html

Utilize keywords within the Codex session for predefined workflows. Use `$deep-interview` for clarification, `$ralplan` for planning, and `$ralph` for completion.

```bash
# 2. Use keywords inside Codex for workflows
$deep-interview "clarify the auth change"
$ralplan "approve the implementation plan"
$ralph "carry the plan to completion"
```

--------------------------------

### Initialize Tmux Prompt Injection

Source: https://oh-my-codex.dev/docs.html

Initialize tmux prompt injection workaround. This command helps in setting up a workaround for tmux prompt injection issues.

```bash
omx tmux-hook init
```

--------------------------------

### Advanced Team Configuration with BASH

Source: https://oh-my-codex.dev/docs.html

Use BASH environment variables to configure advanced team behaviors, such as mixing AI providers, forcing specific models, or enabling dynamic scaling.

```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"

```

--------------------------------

### Oh My Codex Core Commands

Source: https://oh-my-codex.dev/docs.html

A reference for the primary commands available in the Oh My Codex CLI, detailing their functionality for launching the CLI, setting up skills, initializing agents, checking health, querying advisors, resuming sessions, exploring repositories, and managing teams.

```bash
omx
```

```bash
omx setup
```

```bash
omx agents-init .
```

```bash
omx doctor
```

```bash
omx ask <provider>
```

```bash
omx resume
```

```bash
omx explore
```

```bash
omx sparkshell
```

```bash
omx team
```

```bash
omx ralph
```

```bash
omx status
```

```bash
omx cancel
```

```bash
omx hud
```

```bash
omx reasoning [mode]
```

```bash
omx version
```

```bash
omx help
```

--------------------------------

### Mix AI Providers in a Team (BASH)

Source: https://oh-my-codex.dev/docs.html

Configure a team to use multiple AI providers like Codex, Gemini, and Claude by setting the OMX_TEAM_WORKER_CLI_MAP environment variable.

```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: Create Task

Source: https://oh-my-codex.dev/docs.html

Programmatically create a new task within a team using the `omx team api create-task` command with JSON input.

```bash
# Create a task programmatically
omx team api create-task --input '{"team_name":"my-team","subject":"Fix bug","description":"..."}' --json

```

--------------------------------

### Launch Team in New Worktree

Source: https://oh-my-codex.dev/docs.html

Use this command to launch a team in a new, dedicated git worktree. This prevents conflicts between parallel workers. Ensure the worktree name is descriptive of the feature.

```bash
# Launch in a new worktree
omx team 4:executor "feature work" --worktree=feature-branch
```

--------------------------------

### Watch HUD Output

Source: https://oh-my-codex.dev/docs.html

Watch runtime state and HUD output live. This command is useful for monitoring the application's real-time status.

```bash
omx hud --watch
```

--------------------------------

### Manage Team Worktrees with OMX

Source: https://oh-my-codex.dev/docs.html

Use `omx team` commands to manage worker worktrees, check their status, and configure mixed provider environments. Ensure workers commit changes before reporting completion.

```bash
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"
```

--------------------------------

### Team CLI API: Transition Task Status

Source: https://oh-my-codex.dev/docs.html

Transition the status of a claimed task using `omx team api transition-task-status`, specifying the current and target states along with the claim token.

```bash
# 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

```

--------------------------------

### Configure TOML Notifications

Source: https://oh-my-codex.dev/docs.html

Set up notifications for Codex using TOML format. This includes enabling Telegram and Slack notifications with specific tokens and chat IDs.

```toml
[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"

```

--------------------------------

### OpenClaw Notification Configuration

Source: https://oh-my-codex.dev/docs.html

Configure OpenClaw for production-grade notification orchestration, enabling agent turns and complex follow-up behaviors. This JSON defines notification settings and hooks.

```json
{
  "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}}"
        }
      }
    }
  }
}
```

--------------------------------

### Configure JSON Notifications

Source: https://oh-my-codex.dev/docs.html

Configure advanced notification routing using JSON format, including custom webhook commands and CLI commands with event filtering.

```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"]
    }
  }
}

```

--------------------------------

### Oh My Codex Launch Flags

Source: https://oh-my-codex.dev/docs.html

Reference for launch flags that modify the behavior of the Oh My Codex CLI, such as enabling yolo mode, setting reasoning effort, bypassing approvals, using the spark model, or launching in a git worktree.

```bash
--yolo
```

```bash
--high / --xhigh
```

```bash
--madmax
```

```bash
--spark
```

```bash
--madmax-spark
```

```bash
-w, --worktree[=<name>]
```

```bash
--force
```

```bash
--dry-run
```

```bash
--verbose
```

```bash
--scope <user|project>
```

--------------------------------

### Emit HUD Status as JSON

Source: https://oh-my-codex.dev/docs.html

Emit HUD status as machine-readable JSON. This is useful for integrating HUD data into other systems or for programmatic analysis.

```bash
omx hud --json
```

--------------------------------

### Execute $team for Parallel Execution

Source: https://oh-my-codex.dev/index.html

Use the `$team` skill for coordinated parallel execution. Each worker runs in an isolated git worktree by default, preventing merge conflicts.

```bash
# Use $team inside Codex (recommended)
$team 3:executor "refactor auth module"
Team started: refactor-auth-module
workers: 3 (worktrees: automatic, detached)
```

--------------------------------

### Advanced CLI Operator Surface for $team

Source: https://oh-my-codex.dev/index.html

Interact with the team functionality directly from the command line. Use `omx team status` to check the status of a team.

```bash
# Advanced: CLI operator surface
omx team 3:executor "refactor auth module"
omx team status refactor-auth-module
```

--------------------------------

### Validate Hook Plugin Implementation

Source: https://oh-my-codex.dev/docs.html

Validate the implementation of a hook plugin. This command ensures that your hook plugins are correctly implemented according to OMX standards.

```bash
omx hooks validate
```

--------------------------------

### Team CLI API: Claim Task

Source: https://oh-my-codex.dev/docs.html

Claim a task using the `omx team api claim-task` command, ensuring versioned safety with the provided worker ID and JSON input.

```bash
# Claim a task with versioned safety
omx team api claim-task --input '{"team_name":"my-team","task_id":"1","worker":"worker-1"}' --json

```

--------------------------------

### Resume Interrupted Team

Source: https://oh-my-codex.dev/docs.html

If a worker fails or a session is interrupted, OMX preserves the state in `.omx/state/team/`. Use this command to safely resume the team's tasks.

```bash
omx team resume <team-name>
```
Tokens:
Raw