oh-my-codex (OMX)

oh-my-codex (OMX) 不是一个替代 OpenAI Codex CLI 的新工具，而是一个强大的工作流编排层。它旨在解决开发者在使用 Codex 时面临的常见痛点：提示词不一致、任务边界模糊、缺乏持久化记忆以及难以协调并行任务。

OMX 保留了 Codex 作为核心执行引擎，但在其之上构建了一套标准化的角色系统、技能库和项目状态管理机制，让 AI 编程从“单次对话”进化为“结构化工程协作”。

核心理念：更好的路由 + 更好的工作流

OMX 的设计哲学非常清晰：

• Codex 负责“做”（执行代码、调用工具）。
• OMX 负责“管”（澄清需求、规划路径、分配角色、记录状态）。

通过引入 $deep-interview, $ralplan, $ralph, $team 等专用指令，OMX 强制 AI 遵循从需求澄清到计划审批再到执行验证的严谨工程流程，显著减少幻觉和返工。

快速开始：三步开启超级模式

1. 安装依赖

确保已安装 Node.js 20+ 和 Codex CLI。

npm install -g @openai/codex oh-my-codex
omx setup  # 初始化配置文件、技能和 AGENTS.md 脚手架

2. 启动增强会话

使用推荐的高性能模式启动：

omx --madmax --high

• --madmax: 启用最大并发和激进优化。
• --high: 提升模型推理优先级和资源配额。

3. 体验标准工作流

在 Codex 会话中，不再直接扔给 AI 一个模糊的需求，而是按以下步骤操作：

# 第一步：澄清需求（当任务边界模糊时）
$deep-interview "clarify the authentication change requirements and non-goals"

# 第二步：规划与审批（生成架构方案并权衡利弊）
$ralplan "approve the safest implementation path for auth change"

# 第三步：执行（二选一）
# 选项 A：单人持久化完成循环（适合中等任务）
$ralph "carry the approved plan to completion with verification"

# 选项 B：多人并行执行（适合大型重构或复杂功能）
$team 3:executor "execute the approved plan in parallel with code review"

核心功能详解

1. 标准化角色技能 (Specialized Roles)

OMX 预置了四个核心“元技能”，覆盖软件开发生命周期的关键节点：

2. 项目级持久化记忆 (.omx/)

OMX 会在项目根目录创建 .omx/ 文件夹，用于存储：

• Plans: 已批准的实施计划。
• Logs: 详细的执行日志和决策记录。
• Memory: 跨会话的项目上下文和模式跟踪。
• Status: 当前任务的状态机信息。
  这使得 AI 能够“记住”昨天的进度，即使你关闭了终端。

3. 项目指导 (AGENTS.md)

支持在项目根目录定义 AGENTS.md 文件，作为团队的“宪法”。你可以在此规定：

• 代码风格规范。
• 禁止使用的库或模式。
• 特定的测试策略。
  OMX 会自动将此文件注入每次会话的 System Prompt，确保 AI 行为符合团队标准。

4. 团队运行时 (Team Runtime)

对于超大型任务，OMX 支持基于 tmux (macOS/Linux) 或 psmux (Windows) 的真实并行执行环境：

• 隔离工作区：每个子 Agent 在独立的 tmux pane 或 git worktree 中工作，互不干扰。
• 状态监控：使用 omx team status 实时查看各成员进度。
• 灵活控制：支持暂停 (pause)、恢复 (resume) 和关闭 (shutdown) 整个团队。

高级用法与工具

探索与诊断

• omx explore --prompt "...": 只读模式，快速查找代码库中特定逻辑的位置，不修改文件。
• omx doctor: 一键诊断环境配置、依赖项和权限问题。
• omx hud --watch: 实时监控面板，显示当前运行的 Agent 状态、Token 消耗和任务进度。

Sparkshell (原生 Shell 桥接)

允许在 OMX 上下文中直接运行原生 Shell 命令，并智能解析输出：

omx sparkshell git status
omx sparkshell --tmux-pane %12 --tail-lines 400  # 监控特定 tmux 窗格输出

注意事项与已知问题

平台依赖

• macOS / Linux: 需要安装 tmux (brew install tmux / apt install tmux) 以启用团队模式。
• Windows: 原生 Windows 需安装 psmux (winget install psmux)；WSL2 用户直接使用 tmux。

Intel Mac 性能问题

在部分 Intel Mac 上，使用 --madmax --high 启动时可能触发 macOS Gatekeeper 的频繁验证，导致 syspolicyd CPU 飙升。
解决方案：

# 移除隔离属性
xattr -dr com.apple.quarantine $(which omx)
# 或将终端应用加入 macOS 安全设置的“开发者工具”白名单