Oh-My-Codex 项目介绍

Oh-My-Codex (OMX) 项目介绍

项目定位

OMX 是 OpenAI Codex CLI 的工作流编排层 —— 它不替换 Codex，而是在 Codex 之上叠加专业的角色分工、可复用的工作流技能、持久化的状态管理和并行的团队运行时。

一句话：OMX 把 Codex 从一个”能帮你写代码的 AI”变成”能像工程团队一样完成从需求澄清到部署验证全生命周期的 AI 系统”。

核心能力

能力	说明
三阶段标准工作流	$deep-interview（需求澄清）→ $ralplan（方案审批）→ $ultragoal（持久化多目标执行）
40+ 专业 Agent 角色	探索者、分析师、架构师、规划师、执行者、验证者、代码审查员等，每个角色有独立的提示词、模型路由和推理强度
35+ 工作流技能	以 SKILL.md 文件形式定义的可复用工作流，覆盖规划、执行、审查、研究、设计等场景
持久化多目标执行	$ultragoal 将计划拆解为可独立追踪的子目标，通过 .omx/ultragoal/ledger.jsonl 审计日志实现跨会话持久化
持久完成循环	$ralph 实现”不停止直到完成”的单任务迭代循环，内置完成审计、架构师验证和回归检查
tmux 团队运行时	omx team 创建带 HUD 的 tmux 会话，每个 worker 拥有独立的 git worktree，通过文件邮箱和分派队列通信
Codex 原生 Hook 集成	通过 Codex 的 SessionStart、UserPromptSubmit、PreToolUse、PostToolUse、Stop 等生命周期事件实现技能路由、关键词检测和自动推进
git worktree 隔离	--worktree 标志为每个并发任务创建独立的 git 工作树，避免并行修改冲突
模型路由与分层	Agent 按 frontier/standard/fast 模型层级自动路由，--high/--xhigh 控制推理强度
状态持久化	.omx/ 目录存储计划、日志、记忆、模式状态和审计轨迹，支持跨会话恢复

技术栈

层	技术
运行时	Node.js 20+，TypeScript
包管理	npm，全局安装 (npm install -g oh-my-codex)
底层引擎	OpenAI Codex CLI（OMX 本身不执行代码，依赖 Codex）
终端管理	tmux（macOS/Linux），psmux（Windows）
原生组件	Rust crates（omx-explore 探索引擎、omx-mux 终端复用器）
配置	TOML（Codex 配置），JSON（OMX 状态），Markdown（SKILL.md / AGENTS.md）
依赖	zod（类型验证），@modelcontextprotocol/sdk（MCP 协议），@iarna/toml（TOML 解析）
构建	TypeScript 编译器（tsc），Biome（lint）
插件	Codex 插件系统（plugins/oh-my-codex/）

架构概览

快速体验

前置条件

# 1. 安装 Codex CLI（Homebrew 或 npm）
codex --version

# 2. 安装 OMX
npm install -g oh-my-codex

# 3. 安装 tmux（macOS/Linux）
brew install tmux  # macOS
sudo apt install tmux  # Ubuntu

# 4. 初始化
omx setup
omx doctor

# 5. 执行测试
omx exec --skip-git-repo-check -C . "Reply with exactly OMX-EXEC-OK"

典型工作流

# 从 git 项目启动（推荐：使用 worktree 隔离）
omx --worktree=feat/task --madmax --high

# 在 Codex 会话中：
# 1. 需求澄清
$deep-interview "clarify the authentication change"

# 2. 方案审批
$ralplan "approve the safest implementation path"

# 3. 持久化多目标执行
$ultragoal "turn the approved plan into durable goals"

OMX exec（无 TTY 环境）

# 非交互式执行（适合 CI/自动化）
omx exec --skip-git-repo-check -C . "Review src/cli/index.ts for security issues"

团队运行时

# 创建带 3 个 worker 的团队会话
omx team 3:executor "fix the failing tests with verification"

# 查看团队状态
omx team status <team-name>

教程导读

本教程分为 AI 和 Dev 两个部分：

AI 教程（通用知识抽取）

章节	知识点	Common 引用
01. Agent 角色系统	40+ 专业角色的定义、路由与行为叠加	引用 多 Agent 路由
02. 技能系统设计	SKILL.md 结构、关键词检测、意图门控	引用 技能设计
03. 工作流编排模式	$deep-interview → $ralplan → $ultragoal 流水线	引用 Agent 工作流
04. 持久化多目标执行	目标拆解、审计日志、动态转向系统	—
05. 持久完成循环	单任务迭代、完成审计、架构师验证	引用 质量门控
06. 提示词叠加层与系统提示组装	AGENTS.md 运行时注入、代码地图、压缩协议	引用 系统提示

Dev 教程（工程实践）

章节	知识点
01. CLI 架构与启动编排	omx CLI 的命令路由、标志规范化、启动流水线
02. Codex 原生 Hook 集成	SessionStart / UserPromptSubmit / Stop 等生命周期事件
03. tmux 团队运行时架构	tmux 分窗、worktree 隔离、文件邮箱通信
04. git worktree 并发隔离	工作树创建、交叉 rebase、合并策略
05. 通知与回退系统	notify-hook、回退轮询、自动推进
06. 插件系统与发布流水线	Codex 插件布局、技能同步、npm 发布