Yeachan-Heo/oh-my-codex

oh‑my‑codex (OMX) – OpenAI Codex 的工作流層

是什麼 – OMX 是一個輕量級的 CLI 包裝器，位於官方 OpenAI Codex 命令列工具之上。它不取代 Codex 的程式碼產生引擎；而是新增結構化、有明確立場的工作流程、持久的專案狀態，以及一組可重複使用的「技能」（命令），使日常提示操作更具可重複性。

為何存在 – 許多使用 Codex 的開發者報告稱，他們必須重複相同的步驟：明確任務、取得計畫、核准計畫，然後執行計畫。OMX 將此模式形式化為 $deep‑interview → $ralplan → $ultragoal（可選更嚴格的變體），並將中間成果物儲存在隱藏的 .omx/ 資料夾中。這為您帶來：

• 一個 單一入口點（omx），可使用正確的模型設定（高努力推理，可選的「madmax」繞過沙箱檢查）啟動 Codex 會話，
• 透過 AGENTS.md 檔案實現 專案範圍的指導，可合併或獨立保留，
• 持久的日誌、計畫和檢查點，以便恢復或審計長時間執行的重構，
• macOS/Linux 上的 tmux 基礎 UI，將終端分為 HUD 和 Codex 面板，使多面板互動更順暢。

如何取得

# 如果您已有 Codex CLI（透過 Homebrew、npm 等）
npm install -g oh‑my‑codex
# 否則先安裝 Codex
npm install -g @openai/codex
npm install -g oh‑my‑codex

安裝後執行一次設定：

omx setup --scope project --merge-agents   # 在您希望 OMX 管理的倉儲內執行
# 或
omx setup --scope user                     # 用於全域使用者級設定

然後驗證一切正常：

omx doctor                     # 檢查相依性與執行時檔案
omx exec -C . "Reply with exactly OMX‑EXEC‑OK"   # 對真實 Codex 呼叫進行煙霧測試

典型工作流程

1. 啟動會話（建議在 git worktree 中以實現隔離）：

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

2. 澄清 – $deep‑interview "…" – 讓 Codex 提出後續問題並完善問題陳述。
3. 計畫 – $ralplan "…" – 取得具體的架構/實作計畫並核准。
4. 執行 – 以下執行脊柱之一：
   • $ultragoal / $ultrawork – 持久化、帶檢查點的執行，.omx/ultragoal 中有帳本記錄。
   • $autopilot – 從訪談到執行的完整監督循環。
   • $ralph – 適用於簡單任務的單所有者循環。
   • $prometheus‑strict – 為高風險變更添加額外的批判步驟。
5. 可選研究 – $best‑practice‑research、$autoresearch、$autoresearch‑goal 在計畫前拉取外部證據。

核心概念與命令

概念	含義	典型命令
Worktree	用作執行時根目錄的隔離 git 檢出。	omx --worktree=feature/auth …
MADMAX	--dangerously-bypass-approvals-and-sandbox 的快捷方式；禁用 Codex 的安全防護（僅在可信倉儲中使用）。
模型努力	--high / --xhigh 設定 model_reasoning_effort，向 Codex 請求更多計算資源。
AGENTS.md	持久化指導檔案（全域或專案範圍），定義角色、安全規則和路由。
.omx/	計畫、日誌、記憶體快照和帳本檔案存放的目錄。
技能	內建命令快捷方式（$deep‑interview、$ralplan、$ultragoal 等），呼叫特定 Codex 提示。
團隊模式	omx team 啟動 tmux 管理的多面板會話，支援並行工作。
直接模式	omx --direct 無 tmux UI 執行 Codex，適合在現有終端中使用。

適用對象

• 已熟悉 OpenAI Codex CLI 但希望獲得可重複、有狀態工作流程的開發者。
• 需要 專案級指導（透過 AGENTS.md）並希望保留計畫和執行檢查點記錄的團隊。
• 使用 macOS/Linux 的使用者（預設、完全支援路徑）。Windows 支援存在但穩定性較低。

限制/注意事項

• 主要針對 macOS/Linux 優化；Windows 可能出錯或行為不一致。
• 「madmax」標誌禁用安全檢查 – 僅在可信程式碼庫中使用。
• OMX 依賴於一個正常運作的、已認證的 codex 二進位檔；它不管理認證本身。
• 啟動時檢查更新；可透過 OMX_AUTO_UPDATE 禁用或推遲更新。

專案健康狀況

• 發布於 npm（oh‑my‑codex），版本徽章顯示活躍發行。
• 由原始作者（Yeachan Heo）及小團隊貢獻者維護。
• 文件詳盡（入門、代理、技能、整合），並提供 Discord 社群支援。

總結 – 如果您已使用 Codex 且發現自己在手動編排提示，OMX 可為您提供現成的、可腳本化的流程、持久狀態和更豐富的終端 UI，將臨時提示工程轉變為可重複的開發流程。