oh-my-codex-workflow

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Oh My Codex (OMX) Workflow

Oh My Codex (OMX) 工作流

Skill by ara.so — Codex Skills collection.

由ara.so开发的Skill——Codex Skills合集。

What OMX Does

OMX 功能介绍

Oh My Codex (OMX) is a workflow layer for OpenAI Codex CLI that enhances the base Codex experience with:

Canonical workflow:
```
$deep-interview
```
→
```
$ralplan
```
→
```
$ralph
```
or
```
$team
```
Agent teams: Coordinated parallel execution with tmux-backed worktrees
Persistent state: Plans, logs, memory, and mode tracking in
```
.omx/
```
Role keywords: Reusable specialist roles (executor, architect, reviewer, etc.)
Skills system: Installable workflows like
```
$deep-interview
```
,
```
$ralplan
```
,
```
$team
```
,
```
$ralph
```
Project guidance: Scoped
```
AGENTS.md
```
for project-specific context
Runtime hooks: Native Codex lifecycle integration via
```
.codex/hooks.json
```

OMX keeps Codex as the execution engine and adds better task routing, workflow orchestration, and runtime support around it.

Oh My Codex (OMX) 是为OpenAI Codex CLI打造的工作流层，在基础Codex体验上新增了以下功能：

标准工作流：
```
$deep-interview
```
→
```
$ralplan
```
→
```
$ralph
```
或
```
$team
```
Agent团队：基于tmux工作树的协同并行执行
持久化状态：在
```
.omx/
```
目录中存储计划、日志、记忆与模式跟踪信息
角色关键词：可复用的专家角色（执行者、架构师、审核者等）
技能系统：可安装的工作流，如
```
$deep-interview
```
、
```
$ralplan
```
、
```
$team
```
、
```
$ralph
```
项目指引：针对特定项目上下文的
```
AGENTS.md
```
文件
运行时钩子：通过
```
.codex/hooks.json
```
原生集成Codex生命周期

OMX 保留Codex作为执行引擎，在其基础上增强了任务路由、工作流编排与运行时支持能力。

Installation

安装步骤

Prerequisites

前置条件

Node.js 20+
Codex CLI:
```
npm install -g @openai/codex
```
Configured Codex auth (check with
```
codex login status
```
)
```
tmux
```
on macOS/Linux for team runtime (optional but recommended)

Node.js 20+
Codex CLI：
```
npm install -g @openai/codex
```
已配置Codex认证（可通过
```
codex login status
```
检查）
团队运行时需在macOS/Linux上安装
```
tmux
```
（可选但推荐）

Install OMX

安装OMX

bash

undefined

bash

undefined

Install both Codex CLI and OMX globally

全局安装Codex CLI与OMX

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

Run setup to install prompts, skills, hooks, and scaffolding

运行安装向导，配置提示词、技能、钩子与脚手架

omx setup

Verify installation

验证安装状态

omx doctor

Smoke test actual Codex execution

执行冒烟测试，验证Codex实际运行能力

omx exec --skip-git-repo-check -C . "Reply with exactly OMX-EXEC-OK"

undefined

omx exec --skip-git-repo-check -C . "Reply with exactly OMX-EXEC-OK"

undefined

Update OMX

更新OMX

bash

undefined

bash

undefined

Check npm, install latest, and refresh setup

检查npm版本、安装最新版并刷新配置

omx update

Or manually:

或手动更新：

npm install -g oh-my-codex omx setup

undefined

npm install -g oh-my-codex omx setup

undefined

Core Workflow

核心工作流

The Recommended Path

1. Launch OMX with recommended settings

1. 使用推荐配置启动OMX

omx --madmax --high

Inside the Codex session:

在Codex会话内：

2. Clarify scope (when boundaries are unclear)

2. 当边界不清晰时，澄清范围

$deep-interview "clarify the authentication change"

3. Create and approve implementation plan

3. 创建并批准实施计划

$ralplan "approve the auth plan and review tradeoffs"

4a. Execute with persistent completion loop

4a. 通过持久化完成循环执行任务

$ralph "carry the approved plan to completion"

OR 4b. Execute with coordinated parallel team

或 4b. 通过协同并行团队执行任务

$team 3:executor "execute the approved plan in parallel"

5. Convert to durable goals (for multi-session work)

5. 将任务转换为持久化目标（用于多会话工作）

$ultragoal "turn this launch into durable Codex goals"

undefined

$ultragoal "turn this launch into durable Codex goals"

undefined

Launch Modes

启动模式

bash

undefined

bash

undefined

Default: auto-managed tmux on macOS/Linux interactive terminals

默认模式：在macOS/Linux交互式终端中自动管理tmux

omx --madmax --high

Direct mode (no OMX tmux/HUD management)

直接模式（不启用OMX的tmux/HUD管理）

omx --direct --yolo

Set persistent preference via environment

通过环境变量设置持久化偏好

export OMX_LAUNCH_POLICY=direct # or tmux, detached-tmux, auto omx --yolo

export OMX_LAUNCH_POLICY=direct # 可选值：tmux, detached-tmux, auto omx --yolo

CLI flags override environment (last flag wins)

CLI参数会覆盖环境变量（最后一个参数生效）

OMX_LAUNCH_POLICY=direct omx --tmux --yolo # Uses tmux

undefined

OMX_LAUNCH_POLICY=direct omx --tmux --yolo # 使用tmux模式

undefined

Canonical Skills

标准技能

$deep-interview

Clarify intent, boundaries, and non-goals when the request is vague.

text

$deep-interview "clarify requirements for the new API endpoint"
$deep-interview "understand the performance bottleneck before planning fixes"

当需求模糊时，澄清意图、边界与非目标。

text

$deep-interview "clarify requirements for the new API endpoint"
$deep-interview "understand the performance bottleneck before planning fixes"

$ralplan

Turn clarified scope into an approved architecture and implementation plan.

text

$ralplan "approve the implementation plan and review tradeoffs"
$ralplan "verify the migration strategy is safe"

将已澄清的范围转换为已批准的架构与实施计划。

text

$ralplan "approve the implementation plan and review tradeoffs"
$ralplan "verify the migration strategy is safe"

$ralph

Persistent completion loop - one owner keeps pushing until done.

text

$ralph "carry the approved plan to completion"
$ralph "implement the auth changes with verification"

持久化完成循环——由单个执行者推进任务直至完成。

text

$ralph "carry the approved plan to completion"
$ralph "implement the auth changes with verification"

$team

Coordinated parallel execution with tmux-backed worktrees.

text

undefined

基于tmux工作树的协同并行执行。

text

undefined

Launch team with N agents of role:type

启动N个指定角色类型的Agent团队

$team 3:executor "execute the approved plan in parallel" $team 2:architect "design the new service architecture"

Team management (CLI, not in-session)

团队管理（通过CLI执行，非会话内命令）

omx team status <team-name> omx team resume <team-name> omx team shutdown <team-name>

undefined

omx team status <team-name> omx team resume <team-name> omx team shutdown <team-name>

undefined

$ultragoal

Convert a launch session into durable Codex goals for multi-session work.

text

$ultragoal "turn this migration into sequential Codex goals"

将单次启动会话转换为持久化Codex目标，用于多会话工作。

text

$ultragoal "turn this migration into sequential Codex goals"

Project Structure

项目结构

OMX creates and manages these directories:

.omx/
├── plans/           # Approved implementation plans from $ralplan
├── logs/            # Execution logs from $ralph and $team
├── memory/          # Persistent agent memory
├── ultragoal/       # Durable multi-goal artifacts
└── teams/           # Team runtime state and worktrees

.codex/
├── config.toml      # Codex configuration (OMX seeds defaults)
├── hooks.json       # Native Codex hooks (OMX-managed wrappers)
└── prompts/         # OMX-installed role and skill prompts

AGENTS.md            # Project-specific agent guidance (optional)

OMX会创建并管理以下目录：

.omx/
├── plans/           # 来自$ralplan的已批准实施计划
├── logs/            # $ralph与$team的执行日志
├── memory/          # Agent持久化记忆
├── ultragoal/       # 持久化多目标工件
└── teams/           # 团队运行时状态与工作树

.codex/
├── config.toml      # Codex配置（OMX会填充默认值）
├── hooks.json       # 原生Codex钩子（OMX管理的包装器）
└── prompts/         # OMX安装的角色与技能提示词

AGENTS.md            # 项目特定的Agent指引（可选）

Configuration

配置说明

Model and Environment Routing

模型与环境路由

Edit

.omx-config.json

for model/env routing (only use keys supported by your OMX version):

json

{
  "model": "gpt-5.5",
  "provider": "openai",
  "baseURL": "https://api.openai.com/v1",
  "env": {
    "OPENAI_API_KEY": "${OPENAI_API_KEY}"
  }
}

See model/env routing reference for details.

编辑

.omx-config.json

配置模型/环境路由（仅使用OMX版本支持的键）：

json

{
  "model": "gpt-5.5",
  "provider": "openai",
  "baseURL": "https://api.openai.com/v1",
  "env": {
    "OPENAI_API_KEY": "${OPENAI_API_KEY}"
  }
}

详情请查看模型/环境路由参考文档。

Codex Config Seeding

Codex配置填充

OMX seeds

.codex/config.toml

with recommended defaults for

gpt-5.5

toml

[gpt-5.5]
model_name = "gpt-5.5"
model_context_window = 250000
model_auto_compact_token_limit = 200000

OMX会为

gpt-5.5

在

.codex/config.toml

中填充推荐默认值：

toml

[gpt-5.5]
model_name = "gpt-5.5"
model_context_window = 250000
model_auto_compact_token_limit = 200000

AGENTS.md Merge

AGENTS.md合并

Preserve existing project guidance while adding OMX sections:

bash

undefined

保留现有项目指引的同时添加OMX相关内容：

bash

undefined

Merge mode: inserts between  / END -->

合并模式：在 / END -->之间插入内容

omx setup --merge-agents

Default: skips existing AGENTS.md in non-interactive mode

默认模式：非交互模式下跳过现有AGENTS.md

omx setup

undefined

omx setup

undefined

Common Patterns

常见模式

Standard Workflow

标准工作流

typescript

// TypeScript example: typical OMX workflow pattern
async function standardWorkflow() {
  // 1. Clarify scope
  // Run: $deep-interview "understand the feature requirements"
  
  // 2. Create plan
  // Run: $ralplan "approve the implementation approach"
  
  // 3. Execute
  // Option A - single persistent owner:
  // Run: $ralph "implement with verification"
  
  // Option B - parallel team:
  // Run: $team 3:executor "execute in parallel"
  
  // 4. Convert to goals for multi-session work
  // Run: $ultragoal "create durable goals for remaining work"
}

typescript

// TypeScript示例：典型OMX工作流模式
async function standardWorkflow() {
  // 1. 澄清范围
  // 执行：$deep-interview "understand the feature requirements"
  
  // 2. 创建计划
  // 执行：$ralplan "approve the implementation approach"
  
  // 3. 执行任务
  // 选项A - 单个持久化执行者：
  // 执行：$ralph "implement with verification"
  
  // 选项B - 并行团队：
  // 执行：$team 3:executor "execute in parallel"
  
  // 4. 转换为多会话工作的目标
  // 执行：$ultragoal "create durable goals for remaining work"
}

Team Execution

团队执行

bash

undefined

bash

undefined

Launch team from CLI

从CLI启动团队

omx team 3:executor "migrate database schema with verification"

Check team status

检查团队状态

omx team status migration-team

Resume paused team

恢复暂停的团队

omx team resume migration-team

Clean shutdown

优雅关闭团队

omx team shutdown migration-team

undefined

omx team shutdown migration-team

undefined

Direct Codex Exec

直接Codex执行

typescript

// Use omx exec for one-off Codex calls outside a session
import { execSync } from 'child_process';

const result = execSync(
  'omx exec --skip-git-repo-check -C . "List all TypeScript files in src/"',
  { encoding: 'utf-8' }
);

console.log(result);

typescript

// 在会话外使用omx exec执行一次性Codex调用
import { execSync } from 'child_process';

const result = execSync(
  'omx exec --skip-git-repo-check -C . "List all TypeScript files in src/"',
  { encoding: 'utf-8' }
);

console.log(result);

Custom Skill Creation

自定义技能创建

bash

undefined

bash

undefined

Skills are stored in .codex/prompts/skills/

技能存储在.codex/prompts/skills/目录下

Create a new skill file:

创建新技能文件：

.codex/prompts/skills/my-custom-skill.md

Content structure:

内容结构：

---

name: my-custom-skill

triggers:

- do custom thing

---

# Skill instructions

# 技能说明

When invoked, this skill should...

调用此技能时，应...

undefined

undefined

CLI Commands

CLI命令

Setup and Verification

安装与验证

bash

omx setup                    # Install prompts, skills, hooks, scaffolding
omx setup --merge-agents     # Preserve existing AGENTS.md while adding OMX sections
omx setup --force            # Force overwrite existing files
omx doctor                   # Verify installation integrity
omx update                   # Check npm, install latest, refresh setup
omx uninstall                # Remove OMX-managed hooks (keep user hooks)

bash

omx setup                    # 安装提示词、技能、钩子与脚手架
omx setup --merge-agents     # 保留现有AGENTS.md内容并添加OMX相关部分
omx setup --force            # 强制覆盖现有文件
omx doctor                   # 验证安装完整性
omx update                   # 检查npm版本、安装最新版并刷新配置
omx uninstall                # 移除OMX管理的钩子（保留用户自定义钩子）

Launch

启动命令

bash

omx --madmax --high          # Recommended default
omx --yolo                   # Quick launch, less safety
omx --direct --yolo          # No OMX tmux management
omx --tmux                   # Force tmux mode

bash

omx --madmax --high          # 推荐默认配置
omx --yolo                   # 快速启动，安全校验较少
omx --direct --yolo          # 不启用OMX的tmux管理
omx --tmux                   # 强制使用tmux模式

Execution

执行命令

bash

omx exec [options] "prompt"                    # Direct Codex execution
omx exec --skip-git-repo-check -C . "prompt"   # Skip git repo requirement

bash

omx exec [options] "prompt"                    # 直接执行Codex调用
omx exec --skip-git-repo-check -C . "prompt"   # 跳过Git仓库检查

Team Runtime

团队运行时命令

bash

omx team N:role "task"       # Launch N agents of role:type
omx team status <name>       # Check team status
omx team resume <name>       # Resume paused team
omx team shutdown <name>     # Clean shutdown
omx team list                # List active teams

bash

omx team N:role "task"       # 启动N个指定角色类型的Agent团队
omx team status <name>       # 检查团队状态
omx team resume <name>       # 恢复暂停的团队
omx team shutdown <name>     # 优雅关闭团队
omx team list                # 列出活跃团队

Monitoring

监控命令

bash

omx hud --watch              # Launch monitoring HUD (operator surface)

bash

omx hud --watch              # 启动监控HUD（操作面板）

Environment Variables

环境变量

bash

undefined

bash

undefined

Launch policy preference

启动策略偏好

export OMX_LAUNCH_POLICY=direct # direct, tmux, detached-tmux, auto

export OMX_LAUNCH_POLICY=direct # 可选值：direct, tmux, detached-tmux, auto

Codex home (affects plugin cache location)

Codex主目录（影响插件缓存位置）

export CODEX_HOME=~/.codex

API keys (referenced in .omx-config.json)

API密钥（在.omx-config.json中引用）

export OPENAI_API_KEY=your_key_here export ANTHROPIC_API_KEY=your_key_here

undefined

export OPENAI_API_KEY=your_key_here export ANTHROPIC_API_KEY=your_key_here

undefined

Troubleshooting

故障排查

Installation Issues

安装问题

bash

undefined

bash

undefined

Verify setup

验证配置

omx doctor

Check Codex auth

检查Codex认证状态

codex login status

Smoke test actual execution

执行冒烟测试验证运行能力

omx exec --skip-git-repo-check -C . "Reply with exactly OMX-EXEC-OK"

Refresh setup after version bump

版本更新后刷新配置

omx setup

Or use update to check npm first

或先通过update检查npm版本

omx update

undefined

omx update

undefined

Team Runtime Issues

团队运行时问题

bash

undefined

bash

undefined

Verify tmux is installed

验证tmux是否安装

which tmux

Check team status

检查团队状态

omx team status <team-name>

Review team logs

查看团队日志

cat .omx/teams/<team-name>/logs/*

Clean shutdown if stuck

若团队卡住，执行优雅关闭

omx team shutdown <team-name>

undefined

omx team shutdown <team-name>

undefined

Hook Issues

钩子问题

bash

undefined

bash

undefined

Verify hooks are registered

验证钩子是否已注册

cat .codex/hooks.json

Refresh OMX-managed hooks (preserves user hooks)

刷新OMX管理的钩子（保留用户自定义钩子）

omx setup

Check hook execution logs

查看钩子执行日志

cat .omx/logs/hooks/*

undefined

cat .omx/logs/hooks/*

undefined

Model/Provider Issues

模型/服务商问题

bash

undefined

bash

undefined

Verify .omx-config.json routing

验证.omx-config.json路由配置

cat .omx-config.json

Check Codex config

检查Codex配置

cat .codex/config.toml

Test with direct exec

通过直接执行测试

omx exec --skip-git-repo-check -C . "test prompt"

Verify env vars are set

验证环境变量是否已设置

echo $OPENAI_API_KEY

undefined

echo $OPENAI_API_KEY

undefined

Common Errors

常见错误

Error: Codex not found

bash

npm install -g @openai/codex

Error: Auth failed

bash

codex login
codex login status

Error: tmux not found (team runtime)

bash

undefined

错误：Codex未找到

bash

npm install -g @openai/codex

错误：认证失败

bash

codex login
codex login status

错误：tmux未找到（团队运行时）

bash

undefined

macOS

brew install tmux

Linux

sudo apt-get install tmux # or yum, dnf, etc.


**Error: Setup refresh skips AGENTS.md**
```bash

sudo apt-get install tmux # 或使用yum、dnf等包管理器


**错误：配置刷新跳过AGENTS.md**
```bash

Use merge mode to preserve existing content

使用合并模式保留现有内容

omx setup --merge-agents

Or force overwrite

或强制覆盖

omx setup --force

undefined

omx setup --force

undefined

Advanced Usage

高级用法

Plugin Mode vs Setup Mode

插件模式 vs 安装模式

OMX ships both as npm package (setup mode) and Codex plugin (plugin mode):

Setup mode (recommended):

bash

npm install -g oh-my-codex
omx setup

Installs native agents and prompts
Manages
```
.codex/hooks.json
```
wrappers
Full runtime integration

Plugin mode:

Install via Codex plugin marketplace
Bundles skills in plugin manifest
Optional MCP compatibility (disabled by default)
Removes legacy OMX-managed prompts to avoid shadowing
Native/runtime hooks still setup-owned
Not a replacement for full OMX setup

OMX同时提供npm包（安装模式）与Codex插件（插件模式）两种形式：

安装模式（推荐）：

bash

npm install -g oh-my-codex
omx setup

安装原生Agent与提示词
管理
```
.codex/hooks.json
```
包装器
完整运行时集成

插件模式：

通过Codex插件市场安装
在插件清单中捆绑技能
可选MCP兼容性（默认禁用）
移除旧版OMX管理的提示词以避免冲突
原生/运行时钩子仍由安装模式管理
无法替代完整OMX安装

Custom Agent Roles

自定义Agent角色

Create custom roles in

.codex/prompts/agents/

markdown

---
name: security-reviewer
role: Security Review Specialist
---

在

.codex/prompts/agents/

目录中创建自定义角色：

markdown

---
name: security-reviewer
role: Security Review Specialist
---

Security Reviewer Agent

安全审核Agent

You are a security review specialist. When assigned a task:

Review code for security vulnerabilities
Check for OWASP top 10 issues
Validate input sanitization
Review authentication/authorization
Document findings with severity levels

undefined

你是一名安全审核专家。分配任务时需执行以下操作：

检查代码中的安全漏洞
排查OWASP Top 10问题
验证输入 sanitization
审核认证/授权机制
按严重程度记录发现的问题

undefined

Integration with Other Tools

与其他工具集成

bash

undefined

bash

undefined

Use OMX in CI/CD

在CI/CD中使用OMX

omx exec --skip-git-repo-check -C . "Run security audit on changed files"

Integrate with git hooks

与Git钩子集成

.git/hooks/pre-commit

#!/bin/bash omx exec -C . "Review staged changes for issues"

undefined

#!/bin/bash omx exec -C . "Review staged changes for issues"

undefined

Best Practices

最佳实践

Start with clarification: Use
```
$deep-interview
```
when scope is unclear
Approve plans explicitly: Always run
```
$ralplan
```
before execution
Choose the right execution mode:
```
$ralph
```
for persistent loops,
```
$team
```
for parallel work
Use durable goals: Run
```
$ultragoal
```
for multi-session work
Review
.omx/
artifacts: Check plans and logs for context
Keep AGENTS.md updated: Maintain project-specific guidance
Verify with
omx doctor
: Run after setup or when issues arise
Test with
omx exec
: Smoke test auth and execution before workflows

从澄清需求开始：当范围不清晰时使用
```
$deep-interview
```
明确批准计划：执行任务前务必运行
```
$ralplan
```
选择合适的执行模式：
```
$ralph
```
适用于持久化循环任务，
```
$team
```
适用于并行工作
使用持久化目标：多会话工作时运行
```
$ultragoal
```
查看
.omx/
工件：检查计划与日志获取上下文信息
更新AGENTS.md：维护项目特定指引
用
omx doctor
验证：安装后或出现问题时执行
用
omx exec
测试：工作流执行前先测试认证与运行能力

Resources

资源链接

Website: https://oh-my-codex.dev
GitHub: https://github.com/Yeachan-Heo/oh-my-codex
Discord: https://discord.gg/PUwSMR9XNk
Documentation:

官网：https://oh-my-codex.dev
GitHub：https://github.com/Yeachan-Heo/oh-my-codex
Discord：https://discord.gg/PUwSMR9XNk
文档：

oh-my-codex-workflow

Original

Translation

Oh My Codex (OMX) Workflow

Oh My Codex (OMX) 工作流

What OMX Does

OMX 功能介绍

Installation

安装步骤

Prerequisites

前置条件

Install OMX

安装OMX

Install both Codex CLI and OMX globally

全局安装Codex CLI与OMX

Run setup to install prompts, skills, hooks, and scaffolding

运行安装向导，配置提示词、技能、钩子与脚手架

Verify installation

验证安装状态

Smoke test actual Codex execution

执行冒烟测试，验证Codex实际运行能力

Update OMX

更新OMX

Check npm, install latest, and refresh setup

检查npm版本、安装最新版并刷新配置

Or manually:

或手动更新：

Core Workflow

核心工作流

The Recommended Path

推荐路径

1. Launch OMX with recommended settings

1. 使用推荐配置启动OMX

Inside the Codex session:

在Codex会话内：

2. Clarify scope (when boundaries are unclear)

2. 当边界不清晰时，澄清范围

3. Create and approve implementation plan

3. 创建并批准实施计划

4a. Execute with persistent completion loop

4a. 通过持久化完成循环执行任务

OR 4b. Execute with coordinated parallel team

或 4b. 通过协同并行团队执行任务

5. Convert to durable goals (for multi-session work)

5. 将任务转换为持久化目标（用于多会话工作）

Launch Modes

启动模式

Default: auto-managed tmux on macOS/Linux interactive terminals

默认模式：在macOS/Linux交互式终端中自动管理tmux

Direct mode (no OMX tmux/HUD management)

直接模式（不启用OMX的tmux/HUD管理）

Set persistent preference via environment

通过环境变量设置持久化偏好

CLI flags override environment (last flag wins)

CLI参数会覆盖环境变量（最后一个参数生效）

Canonical Skills

标准技能

$deep-interview

$deep-interview

$ralplan

$ralplan

$ralph

$ralph

$team

$team

Launch team with N agents of role:type

启动N个指定角色类型的Agent团队

Team management (CLI, not in-session)

团队管理（通过CLI执行，非会话内命令）

$ultragoal

$ultragoal

Project Structure

项目结构

Configuration

配置说明

Model and Environment Routing

模型与环境路由

Codex Config Seeding

Codex配置填充

AGENTS.md Merge