Oh My Codex

https://github.com/yeachan-heo/oh-my-codex
Admin
Oh My Codex is a multi-agent orchestration layer for OpenAI Codex CLI that adds role-based agents,...
Tokens:141,334
Snippets:2,234
Trust Score:9.4
Update:1 month ago
Show doc for...
Tokens:
Raw
### Setup oh-my-codex

Source: https://github.com/yeachan-heo/oh-my-codex/blob/main/DEMO.md

Clones the repository, installs dependencies, and runs the setup command to configure prompts, skills, and the Codex CLI.

```bash
# Clone and install
git clone https://github.com/Yeachan-Heo/oh-my-codex.git
cd oh-my-codex
npm install
npm run build
npm link

# Run setup (installs prompts, skills, configures Codex CLI)
omx setup
```

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

### Verify local source installation

Source: https://github.com/yeachan-heo/oh-my-codex/blob/main/plugins/oh-my-codex/skills/omx-setup/SKILL.md

Use these commands when working with local source code to build and verify the setup.

```bash
npm run build
node dist/cli/omx.js setup --force --verbose
node dist/cli/omx.js doctor
```

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

### Configure OMX Environment

Source: https://github.com/yeachan-heo/oh-my-codex/blob/main/README.md

Initialize the OMX setup at the project or user level, or update the installation.

```bash
omx setup --scope project --merge-agents
```

```bash
omx setup --scope user
```

```bash
omx update
```

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

### Initialize Development Environment

Source: https://github.com/yeachan-heo/oh-my-codex/blob/main/CONTRIBUTING.md

Install dependencies and run standard project checks.

```bash
npm install
npm run lint
npm run build
npm test
```

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

### Install and test the extension

Source: https://github.com/yeachan-heo/oh-my-codex/blob/main/packages/vscode-extension/README.md

Install dependencies and run tests within the extension package directory.

```bash
cd packages/vscode-extension
npm install
npm test
```

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

### Package and install VSIX

Source: https://github.com/yeachan-heo/oh-my-codex/blob/main/packages/vscode-extension/README.md

Package the extension into a VSIX file and install it into the current VS Code instance.

```bash
cd packages/vscode-extension
npx @vscode/vsce package
code --install-extension ./oh-my-codex-vscode-*.vsix --force
```

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

### Install and Verify OMX

Source: https://github.com/yeachan-heo/oh-my-codex/blob/main/README.md

Install the OMX package globally and verify the Codex installation.

```bash
codex --version
```

```bash
npm install -g oh-my-codex
```

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

### Install and run oh-my-codex

Source: https://github.com/yeachan-heo/oh-my-codex/blob/main/README.md

Commands to verify existing installation and execute the tool with specific flags.

```bash
codex --version
npm install -g oh-my-codex
# from the git project you want Codex to edit; choose a task-specific name
omx --worktree=feat/task --madmax --xhigh
```

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

### CLI Status and Version Commands

Source: https://github.com/yeachan-heo/oh-my-codex/blob/main/DEMO.md

Manage session state and verify installation details.

```bash
# Check version
omx version

# Check all active modes
omx status

# Cancel any active mode
omx cancel
```

```text
oh-my-codex vX.Y.Z
Node.js v20+
Platform: linux x64
```

```text
No active modes.
```

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

### Install tmux by platform

Source: https://github.com/yeachan-heo/oh-my-codex/blob/main/README.md

Commands to install the required tmux binary across different operating systems.

```bash
brew install tmux
```

```bash
sudo apt install tmux
```

```bash
sudo dnf install tmux
```

```bash
sudo pacman -S tmux
```

```bash
winget install psmux
```

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

### Start Codex CLI

Source: https://github.com/yeachan-heo/oh-my-codex/blob/main/DEMO.md

Initialize the CLI session within a project directory.

```bash
omx
```

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

### Run OMX setup and initialization commands

Source: https://github.com/yeachan-heo/oh-my-codex/blob/main/plugins/oh-my-codex/skills/omx-setup/SKILL.md

Use these commands to configure the OMX environment or perform lightweight AGENTS.md scaffolding.

```bash
omx setup [--force] [--merge-agents|--no-merge-agents|--clear-merge-agents-policy] [--dry-run] [--verbose] [--scope <user|project>] [--plugin|--legacy|--install-mode <legacy|plugin>] [--mcp <none|compat>] [--no-mcp|--with-mcp] [--disable-team|--enable-team|--team-mode <enabled|disabled>]
omx agents-init [path] [--dry-run] [--force] [--verbose]
```

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

### OMX Setup and Execution Commands

Source: https://github.com/yeachan-heo/oh-my-codex/blob/main/docs/getting-started.html

Commands for managing updates, verifying system health, and initiating the autopilot workflow.

```bash
omx update
```

```bash
omx doctor
```

```bash
codex login status
```

```bash
omx exec
```

```bash
omx --madmax --xhigh
```

```bash
omx --worktree=<task>
```

```bash
$autopilot "ship the auth change"
```

```bash
$deep-interview
```

```bash
$ralplan
```

```bash
$ultragoal
```

```bash
$team
```

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

### Validate setup scope options

Source: https://github.com/yeachan-heo/oh-my-codex/blob/main/docs/migration-mainline-post-v0.4.4.md

Check the help output for available scope configuration flags.

```bash
omx help | rg -e "--scope|project"
```

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

### Configure workspace settings

Source: https://github.com/yeachan-heo/oh-my-codex/blob/main/packages/vscode-extension/README.md

Example configuration for the extension within a VS Code workspace settings file.

```json
{
  "omx.coreModulePath": "/path/to/oh-my-codex/dist/vscode/index.js",
  "omx.defaultArgs": ["--model", "gpt-5-codex"]
}
```

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

### Launch OMX in a git project

Source: https://github.com/yeachan-heo/oh-my-codex/blob/main/README.md

Start the OMX runtime with recommended flags for durable sessions and isolated worktrees.

```bash
omx --worktree=feat/task --madmax --xhigh
```

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

### Multi-skill prompt submission example

Source: https://github.com/yeachan-heo/oh-my-codex/blob/main/docs/STATE_MODEL.md

Demonstrates how to invoke multiple contiguous skill tokens in a single prompt.

```text
$ralplan $team $ralph ship this fix
```

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

### Start performance goal

Source: https://github.com/yeachan-heo/oh-my-codex/blob/main/plugins/oh-my-codex/skills/performance-goal/SKILL.md

Initiates the Codex goal handoff for the specified workflow slug.

```sh
omx performance-goal start --slug startup-latency
```

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

### Launch the Hermes MCP server

Source: https://github.com/yeachan-heo/oh-my-codex/blob/main/docs/hermes-mcp-bridge.md

Command to start the MCP server for Hermes integration.

```bash
omx mcp-serve hermes
```

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

### Verify OMX installation

Source: https://github.com/yeachan-heo/oh-my-codex/blob/main/plugins/oh-my-codex/skills/omx-setup/SKILL.md

Execute these commands to confirm that prompts, skills, and configuration files are correctly set up.

```bash
omx setup --force --verbose
omx doctor
```

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

### Launch OMX Worktree

Source: https://github.com/yeachan-heo/oh-my-codex/blob/main/README.md

Start an OMX session with a specific git worktree and performance flags.

```bash
omx --worktree=feat/task --madmax --xhigh
```

```bash
omx --worktree=feature/auth
```

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

### Install oh-my-codex with npm-managed Codex CLI

Source: https://github.com/yeachan-heo/oh-my-codex/blob/main/docs/getting-started.html

Use this installation path if you do not have the Codex CLI installed and prefer npm to manage it.

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

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

### Install oh-my-codex with existing Codex CLI

Source: https://github.com/yeachan-heo/oh-my-codex/blob/main/docs/getting-started.html

Use this installation path if the Codex CLI is already installed and authenticated on your system.

```bash
codex --version
npm install -g oh-my-codex
omx doctor
```

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

### Install oh-my-codex

Source: https://github.com/yeachan-heo/oh-my-codex/blob/main/docs/index.html

Global installation command for the oh-my-codex package.

```bash
npm install -g oh-my-codex
```

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

### Verify installation

Source: https://github.com/yeachan-heo/oh-my-codex/blob/main/DEMO.md

Runs the doctor command to check the status of the oh-my-codex installation and dependencies.

```bash
omx doctor
```

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

### Sparkshell and Explore Help Commands

Source: https://github.com/yeachan-heo/oh-my-codex/blob/main/docs/qa/explore-sparkshell-heavy-manual-stress.md

Baseline commands to verify the availability and help documentation of the sparkshell and explore modules.

```bash
node bin/omx.js sparkshell --help
node bin/omx.js explore --help
```

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

### Max-quality starter configuration

Source: https://github.com/yeachan-heo/oh-my-codex/blob/main/docs/reference/omx-config-schema-routing.md

Promotes specific roles to max-quality models with explicit reasoning overrides.

```json
{
  "agentModels": {
    "planner": "gpt-5.6-sol",
    "architect": "gpt-5.6-sol",
    "researcher": "gpt-5.6-terra",
    "explore": "gpt-5.6-luna"
  },
  "agentReasoning": {
    "planner": "medium",
    "architect": "xhigh",
    "researcher": "high",
    "explore": "medium",
    "critic": "xhigh"
  },
  "env": {
    "OMX_DEFAULT_FRONTIER_MODEL": "gpt-5.6-sol",
    "OMX_DEFAULT_SPARK_MODEL": "gpt-5.6-luna"
  },
  "models": {
    "default": "gpt-5.6-sol",
    "team": "gpt-5.6-sol",
    "autopilot": "gpt-5.6-sol",
    "ralph": "gpt-5.6-sol",
    "team_low_complexity": "gpt-5.6-luna"
  }
}
```

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

### Quick Add Wiki Page

Source: https://github.com/yeachan-heo/oh-my-codex/blob/main/plugins/oh-my-codex/skills/wiki/SKILL.md

Quickly creates a new wiki page with specified metadata.

```bash
omx wiki wiki_add --input '{"title":"Page Title","content":"...","tags":["tag1"],"category":"decision"}' --json
```

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

### Install Codex CLI via npm

Source: https://github.com/yeachan-heo/oh-my-codex/blob/main/README.md

Commands to install the Codex CLI and oh-my-codex globally using npm.

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

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

### Cost-saving starter configuration

Source: https://github.com/yeachan-heo/oh-my-codex/blob/main/docs/reference/omx-config-schema-routing.md

Routes standard workers to cheaper models and uses the spark lane for low-complexity tasks.

```json
{
  "env": {
    "OMX_DEFAULT_FRONTIER_MODEL": "gpt-5.6-sol",
    "OMX_DEFAULT_STANDARD_MODEL": "gpt-5.6-terra",
    "OMX_DEFAULT_SPARK_MODEL": "gpt-5.6-luna"
  },
  "models": {
    "default": "gpt-5.6-terra",
    "team": "gpt-5.6-sol",
    "team_low_complexity": "gpt-5.6-luna"
  }
}
```

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

### Minimal HUD Preset Output

Source: https://github.com/yeachan-heo/oh-my-codex/blob/main/plugins/oh-my-codex/skills/hud/SKILL.md

Example output for the minimal HUD preset.

```text
[OMX] ralph:3/10 | turns:42
```

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

### Build project

Source: https://github.com/yeachan-heo/oh-my-codex/blob/main/docs/qa/release-readiness-0.18.16.md

Compiles the project source code.

```bash
npm run build
```

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

### Complete UltraGoal Tasks

Source: https://github.com/yeachan-heo/oh-my-codex/blob/main/docs/ultragoal.md

Starts or resumes the next pending goal in the sequence.

```sh
omx ultragoal complete-goals
```

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

### Create Ultragoal plans

Source: https://github.com/yeachan-heo/oh-my-codex/blob/main/plugins/oh-my-codex/skills/ultragoal/SKILL.md

Commands to initialize a new multi-goal plan using various input methods for the brief.

```bash
omx ultragoal create-goals --brief "<brief>"
omx ultragoal create-goals --brief-file <path>
cat <brief> | omx ultragoal create-goals --from-stdin
omx ultragoal create-goals --codex-goal-mode per-story --brief "<brief>"
```

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

### Verify command baseline

Source: https://github.com/yeachan-heo/oh-my-codex/blob/main/docs/qa/explore-sparkshell-heavy-manual-stress.md

Standard commands for verifying the installation and functionality of the omx toolset.

```bash
node bin/omx.js explore --help
```

```bash
node bin/omx.js sparkshell --help
```

```bash
node bin/omx.js sparkshell git --version
```

```bash
node bin/omx.js version
```

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

### Focused HUD Preset Output

Source: https://github.com/yeachan-heo/oh-my-codex/blob/main/plugins/oh-my-codex/skills/hud/SKILL.md

Example output for the default focused HUD preset.

```text
[OMX] ralph:3/10 | ultrawork | team:3 workers | turns:42 | last:5s ago
```

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

### Model Routing Configuration Schema

Source: https://github.com/yeachan-heo/oh-my-codex/blob/main/docs/reference/omx-config-schema-routing.md

Example JSON configuration demonstrating agent models, reasoning overrides, environment fallbacks, and model mode mappings.

```json
{
  "agentModels": {
    "planner": "gpt-5.6-sol",
    "architect": "gpt-5.6-sol",
    "researcher": "gpt-5.6-terra",
    "explore": "gpt-5.6-luna"
  },
  "agentReasoning": {
    "architect": "xhigh",
    "critic": "xhigh"
  },
  "env": {
    "OMX_DEFAULT_FRONTIER_MODEL": "gpt-5.6-sol",
    "OMX_DEFAULT_STANDARD_MODEL": "gpt-5.6-terra",
    "OMX_DEFAULT_SPARK_MODEL": "gpt-5.6-luna"
  },
  "models": {
    "default": "gpt-5.6-sol",
    "team": "gpt-5.6-sol",
    "team_low_complexity": "gpt-5.6-luna"
  }
}
```

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

### Regenerate and verify configuration

Source: https://github.com/yeachan-heo/oh-my-codex/blob/main/docs/reference/omx-config-schema-routing.md

Commands to regenerate setup-managed TOML and verify the resolved configuration scope.

```bash
omx setup --force
omx doctor
```

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

### Build the project

Source: https://github.com/yeachan-heo/oh-my-codex/blob/main/docs/qa/explore-sparkshell-heavy-manual-stress.md

Compiles the TypeScript source and the native sparkshell binary.

```bash
npm run build:full
```
Tokens:
Raw