oh-my-codex (OMX)
npm install -g oh-my-codex · OpenAI Codex CLI のワークフロー強化レイヤー · 上流 v0.20.3 同期
プロジェクト概要
OMX は Codex CLI を置き換えない。Codex を実行エンジンとして維持しながら、再利用可能なロール・ワークフロースキル・永続状態管理を追加するレイヤーです。公式パッケージは oh-my-codex（Yeachan-Heo/oh-my-codex）。
46
Skills
37
Agent Prompts
6
MCP Servers
20+
CLI Commands
3 層メンタルモデル
OMX の構成要素はシンプルな 3 層で理解できます。
L1
Codex CLI（実行エンジン）
エージェントの実際の作業を担当。OMX に置き換わらない。
L2
OMX ロールキーワード & スキル
$deep-interview / $ralplan / $ultragoal などの再利用可能なワークフローを提供。
L3
.omx/ — 永続状態ストレージ
プラン・ログ・メモリ・モード状態をセッションをまたいで保持。
OMX の用途
- Codex をそのまま使いながら より強力なデフォルト起動（例:
omx --worktree=feat/task --madmax --xhigh） $deep-interview→$ralplan→$ultragoalの 推奨ワークフロー（必要時のみ$team/$ralph）$architect/$executorなどの 再利用可能なロール呼び出し$ultragoalによる 複数目標の永続ハンドオフ（.omx/ultragoal）- スコープ付き
AGENTS.mdとomx_wiki/による プロジェクト知識の保持 - プラン・ログ・メモリ・モード追跡のための 永続状態（
.omx/）
v0.20 系の主な変化
- モデル契約を GPT-5.6 世代へ移行 — frontier
gpt-5.6-sol/ standardgpt-5.6-terra/ sparkgpt-5.6-luna - プロジェクト setup のデフォルトが plugin mode（CLI + スコープ付き
AGENTS.mdは引き続き必須） - 推奨起動は named worktree +
--madmax --xhigh。同一 checkout の並列会話は明示的なOMX_ROOTで分離 omx exploreは互換のまま 非推奨。読み取り探索は通常の Codex ツールかomx sparkshellomx capabilities lock|checkとomx missionなどオペレータ向け CLI が増強
いつ OMX は不要か？ Codex をワークフローレイヤー無しで使いたい場合。OMX は付加レイヤーであり、Codex の代替ではありません。
プラットフォーム注意： 推奨デフォルトは macOS / Linux + Codex CLI。ネイティブ Windows と Codex App は副次パスで、挙動が不安定になることがあります。バージョンバンプ後は自動 setup は走らないので、
omx setup --scope project --merge-agents（または --scope user）を手動実行するか、omx update で npm 更新とセットアップ更新をまとめて行います。
前提条件
| 依存 | バージョン | 用途 |
|---|---|---|
Node.js | 20+ | OMX のランタイム |
Codex CLI（codex） | 認証済み | 実行エンジン。Homebrew / npm いずれも可 |
| Codex auth | — | OMX を起動する同一シェル/プロファイルで可視であること |
tmux | 任意 | 推奨の持続チームランタイム（macOS/Linux） |
psmux | 任意 | Windows ネイティブのチームパス（サポート薄い） |
推奨インストールフロー
Step 1
インストール
既存の
codex があれば npm install -g oh-my-codex のみ。無い場合は先に @openai/codex を別途入れる（Homebrew 所有の codex へ npm で上書きしない）。Step 2
スコープ付き setup
対象 git プロジェクトで
omx setup --scope project --merge-agents。ユーザー全域なら --scope user。omx update でも npm 更新後に同じ refresh を実行。Step 3
doctor + exec スモーク
omx doctor でローカル配線を確認し、codex login status と omx exec で実際のモデル呼び出しを検証。Step 4
worktree + madmax 起動
omx --worktree=feat/task --madmax --xhigh で起動。$deep-interview → $ralplan → $ultragoal が本線。# 1. Codex が既にある場合（Homebrew 等）
codex --version
npm install -g oh-my-codex
# Codex が無い場合のみ npm で別途導入
# npm install -g @openai/codex
# ※ Homebrew 所有の /opt/homebrew/bin/codex がある状態で
# npm install -g @openai/codex oh-my-codex をまとめて走らせると EEXIST になり得る
# 2. セットアップ（対象 git プロジェクトで）
omx setup --scope project --merge-agents
# 3. インストール検証 + 実行スモーク
codex login status
omx doctor
omx exec --skip-git-repo-check -C . "Reply with exactly OMX-EXEC-OK"
# 4. 推奨起動（git プロジェクト内）
omx --worktree=feat/task --madmax --xhigh
# セッション内の本線ワークフロー
$deep-interview "clarify the authentication change"
$ralplan "approve the auth plan and review tradeoffs"
$ultragoal "turn the approved plan into durable Codex goals"
並列セッション： 標準起動は選択した
OMX_ROOT を1つ占有する。同じ checkout で追加会話を開くときは
OMX_ROOT="$HOME/.omx/instances/second-conversation" omx のように明示ルートを分ける。
--madmax の並列は named worktree を分ける（同じディレクトリで複数走らせない）。
omx setup の出力（参考）
[1/8] Creating directories... Done.
[2/8] Installing agent prompts... Installed 37 agent prompts.
[3/8] Installing skills... Installed 46 skills.
[4/7] Updating config.toml... Done.
[4.5/7] Verifying Team MCP comm tools...
omx_state exports: team_send_message, team_broadcast,
team_mailbox_list, team_mailbox_mark_delivered
[5/7] Generating AGENTS.md... Generated AGENTS.md in project root.
[6/7] Configuring notification hook... Done.
[7/7] Configuring HUD... HUD config created (preset: focused).
Setup complete! Run "omx doctor" to verify installation.
呼び出し規則
$nameでワークフロースキルまたはロールキーワードを起動/skillsでインストール済みスキルを一覧表示- キーワードは大文字小文字を区別しない。メッセージ内のどこにあってもマッチ。
- 複数のキーワードが同時にマッチした場合は最も具体的なものを使用。
キーワードルーティング（主要スキル）
| キーワード | スキル | 概要 |
|---|---|---|
interview, don't assume | $deep-interview | 要件・境界・非ゴールの明確化（本線の入口） |
ralplan, consensus plan | $ralplan | 合意済みアーキテクチャ/実装計画。計画で止まり、直接実装しない |
ultragoal, multi goal | $ultragoal | 承認済み計画を永続 Codex goals へ（デフォルト完了パス） |
prometheus-strict | $prometheus-strict | 高リスク向けの厳格な計画インタビュー/批判/合成 |
ultrawork, parallel | $ultrawork | チェックポイント付きの耐久実行 |
ralph, don't stop | $ralph | 単一オーナーの持続完了ループ（意図的な代替完了パス） |
autopilot, build me | $autopilot | 計画から実行までの監督付きフルループ |
team, swarm | $team | Ultragoal ストーリー内の協調並列実行（既定の入口ではない） |
plan this, let's plan | $plan | 実装前の計画ワークフロー |
best-practice-research | $best-practice-research | 計画前の公式/上流エビデンス収集 |
analyze, investigate | $analyze | 深層分析・調査 |
ecomode, budget | $ecomode | トークン効率モード |
tdd, test first | $tdd | テスト駆動開発ワークフロー |
code review | $code-review | コードレビュー |
security review | $security-review | OWASP Top 10 セキュリティ監査 |
cancel, stop | $cancel | アクティブモードを終了 |
ロールカタログ（主要 6 ロール）
| ロール | 複雑度 | 主な用途 |
|---|---|---|
explore | Low | 高速コードベース探索・パターン検索 |
planner | Standard | 作業計画とシーケンス構築 |
architect | High | 読み取り専用分析・診断・トレードオフ評価 |
debugger | Standard | 根本原因分析 |
executor | Standard→High | 実装・リファクタリング（実装作業のデフォルト） |
verifier | Standard | 完了証拠収集・バリデーション |
専門ロール（dependency-expert、style-reviewer 等）はスキル/キーワードルーティング経由で利用可能。
使用例
# 本線（明確化→計画承認→永続ゴール）
$deep-interview "clarify the authentication change"
$ralplan "approve the auth plan and review tradeoffs"
$ultragoal "turn the approved plan into durable Codex goals"
# 高リスク計画の硬化（任意）
$prometheus-strict "stress-test the plan before durable execution"
# Ultragoal ストーリー内での並列 / 単一オーナー代替
$team "coordinate parallel stories under the active Ultragoal"
$ralph "keep pushing to completion without a multi-goal ledger"
チームモードの概要
チームモードは tmux ベースのマルチエージェント実行環境です。複数の Codex/Claude ワーカーを1つの tmux セッション内に並列起動し、共有タスクキューで協調させます。Ultragoal ストーリー内ではリーダーが .omx/ultragoal を所有し、ワーカーはチェックポイント証拠を上方向に報告します。
利用タイミング： tmux/ワークツリーによる持続的協調が価値をもたらす場合のみ使用。
デフォルトの作業開始方法として使うのは推奨されない。Codex App や tmux 外セッションではシェルから OMX CLI を起動してから使う。
チームパイプライン
team-plan
→
team-prd
→
team-exec
→
team-verify
→
team-fix
↩ loop
終端状態: complete / failed / cancelled
tmux セッション アーキテクチャ
%%{init: {"theme": "base", "themeVariables": {"primaryColor": "#e8f5ee", "primaryTextColor": "#0d3320", "primaryBorderColor": "#3d9c6a", "lineColor": "#3d9c6a", "secondaryColor": "#f0f0f0", "tertiaryColor": "#fff", "background": "#ffffff", "clusterBkg": "#f5faf7", "clusterBorder": "#3d9c6a"}}}%%
graph TB
subgraph tmux["tmux Session 'omx-team'"]
L["Leader\n(main pane)"]
W1["Worker 1\n(codex)"]
W2["Worker 2\n(codex)"]
W3["Worker N\n(claude)"]
Q["Shared Task Queue\n(durable state)"]
L -- "spawn / monitor" --> W1
L -- "spawn / monitor" --> W2
L -- "spawn / monitor" --> W3
W1 -- "claim/update" --> Q
W2 -- "claim/update" --> Q
W3 -- "claim/update" --> Q
end
MB["Mailbox\n(MCP comm)"] -- "messages" --> W1
MB -- "messages" --> W2
MB -- "messages" --> W3
主なチームコマンド
# 3ワーカーでチーム起動（役割: executor）
omx team 3:executor "fix the failing tests with verification"
# ステータス確認
omx team status <team-name>
# 一時停止後に再開
omx team resume <team-name>
# シャットダウン
omx team shutdown <team-name>
# 混合CLI（Codex + Claude）で6ワーカー起動
export OMX_TEAM_WORKER_CLI_MAP=codex,codex,codex,claude,claude,claude
omx team 6:executor "parallel team smoke"
クレームセーフなタスクライフサイクル
| フェーズ | API 操作 | 説明 |
|---|---|---|
| 作成 | create-task | タスクをキューに追加 |
| クレーム | claim-task | バージョントークン付きでワーカーがタスクを取得 |
| 遷移 | transition-task-status | in_progress → completed 等に状態遷移 |
| 通知 | send-message / broadcast | ワーカー間のメッセージパッシング |
| 確認 | get-summary | JSON エンベロープ（schema_version 1.0）でステータス取得 |
プラットフォーム別 tmux インストール
| プラットフォーム | コマンド |
|---|---|
| macOS | brew install tmux |
| Ubuntu/Debian | sudo apt install tmux |
| Fedora | sudo dnf install tmux |
| Arch | sudo pacman -S tmux |
| Windows | winget install psmux |
| Windows (WSL2) | sudo apt install tmux |
リポジトリ構成
oh-my-codex/
├── src/ # TypeScript ソース（CLI・ランタイムコア）
│ ├── cli/ # コマンド定義（setup, team, doctor, hud...）
│ ├── team/ # チームランタイム（オーケストレーター・ワーカー）
│ ├── ralph/ # 持続的実行ループ
│ ├── pipeline/ # パイプライン管理
│ ├── planning/ # 計画フェーズ
│ ├── agents/ # エージェント初期化・カタログ
│ ├── state/ # .omx/ 状態管理
│ ├── hud/ # HUD 監視ビュー
│ ├── verification/ # 完了検証
│ └── visual/ # ビジュアル出力
├── crates/ # Rust コンポーネント
│ ├── omx-explore/ # 探索ハーネス（CLI 面は非推奨）
│ ├── omx-sparkshell/ # ノイズ削減シェルラッパー
│ ├── omx-api/ # localhost API ゲートウェイ
│ ├── omx-runtime/ # Rust ランタイムコア
│ ├── omx-runtime-core/ # コアライブラリ
│ └── omx-mux/ # tmux マルチプレクサバインディング
├── plugins/ # 公式 Codex plugin レイアウト
├── skills/ # 46 スキル（SKILL.md 形式）
├── prompts/ # 37 エージェントプロンプト（*.md）
├── missions/ # ミッション定義（omx mission）
├── playground/ # リサーチショーケースハブ
├── AGENTS.md # 永続オーケストレーション案内（setup が管理）
└── package.json
.omx/ 永続状態
| パス | 内容 |
|---|---|
.omx/state/ | モード状態（ralph・team・autopilot 等） |
.omx/setup-scope.json | ルートローカルの AGENTS merge ポリシー（update で再生） |
.omx/notepad.md | セッションメモ（notepad MCP / CLI） |
.omx/project-memory.json | クロスセッションプロジェクトメモリ |
.omx/plans/ | PRD・テストスペック・prometheus-strict 成果物 |
.omx/logs/ | 実行ログ |
.omx/ultragoal/ | 複数目標の永続ハンドオフ成果物 |
.omx/missions/ | omx mission の summary / ledger |
6 つの first-party MCP サーバー
| サーバー | 提供ツール |
|---|---|
omx_state | 状態読み書き・チームメッセージング（team_send_message, team_broadcast, mailbox 系） |
omx_memory | プロジェクトメモリ・ノートパッド |
omx_code_intel | コードインテリジェンス（シンボル・パターン検索） |
omx_trace | 実行トレース・デバッグログ |
omx_wiki | プロジェクト wiki（omx_wiki/）の検索・更新（互換 MCP） |
omx_hermes | 外部コーディネータ向けセッション状態・成果物ブリッジ（デフォルト無効） |
Rust コンポーネントの役割
| クレート | 役割 | 呼び出し方 |
|---|---|---|
omx-sparkshell | ノイズの多い読み取り専用コマンドをコンテキスト効率よく実行。 | omx sparkshell <command> |
omx-explore | 探索ハーネス実装。CLI 面 omx explore は非推奨互換。 | 通常の Codex 探索 / sparkshell を使う |
omx-api | localhost API ゲートウェイ。 | omx api serve|status|stop|generate |
omx-mux | tmux セッション管理・ペイン操作バインディング。 | チームランタイム内部 |
omx-runtime | Rust ランタイムコア。 | 内部 |
omx-runtime-core | コアライブラリ（omx-runtime が依存）。 | 内部 |
CLI コマンド一覧
| コマンド | 説明 |
|---|---|
omx / omx --worktree=<name> --madmax --xhigh | Codex CLI を推奨設定で起動（サポート環境では detached tmux が既定） |
omx setup --scope project|user | スキル・プロンプト・config・スコープ付き AGENTS.md をインストール（project は plugin mode 既定） |
omx setup --merge-agents | 既存 AGENTS.md を保持しつつ OMX 区間を挿入/更新。ポリシーは .omx/setup-scope.json に記録 |
omx doctor / omx doctor --team | インストール健全性 / チームランタイム診断 |
omx list | パッケージ済みスキルとネイティブエージェントを一覧（--json） |
omx version | バージョン・Node.js・プラットフォームを表示 |
omx status / omx cancel | アクティブモードの表示 / キャンセル |
omx team <N>:<role> "task" | N ワーカーのチームを起動 |
omx team status|resume|shutdown <name> | チーム状態確認・再開・終了 |
omx mission <file> | プロンプト/チェックリストを omx exec 経由で順次実行 |
omx capabilities lock|check | 設定済み tool/skill/agent/observation 面のロックファイル事前検証 |
omx sparkshell <cmd> | ノイズ削減シェル実行 / tmux pane 要約 |
omx explore | 非推奨互換。新規のリポジトリ探索には使わない |
omx hud --watch | HUD 監視ビュー |
omx exec | 非対話 Codex 実行（認証・実行スモーク用） |
omx update | npm 更新後に setup refresh（--stable / --dev） |
omx wiki | omx_wiki/ の JSON CLI（MCP は互換面） |
omx api | native omx-api localhost ゲートウェイ |
omx cleanup / omx uninstall | 孤立 MCP 掃除 / OMX 成果物削除 |
環境変数（チームモード）
| 変数 | デフォルト | 説明 |
|---|---|---|
OMX_ROOT | checkout 既定 | セッション所有ルート。並列会話は明示的に分離 |
OMX_LAUNCH_POLICY | auto | direct|tmux|detached-tmux|auto（CLI フラグが優先） |
OMX_AUTO_UPDATE | prompt | 0 で起動時更新チェック無効、defer で無プロンプト延期 |
OMX_TEAM_WORKER_CLI | auto | ワーカー CLI の選択モード |
OMX_TEAM_WORKER_CLI_MAP | 自動生成 | ワーカーごとの CLI 割り当て（カンマ区切り） |
OMX_TEAM_WORKER_LAUNCH_ARGS | 低複雑度レーン向け | ワーカー CLI に渡す起動引数 |
OMX_DEFAULT_FRONTIER_MODEL | gpt-5.6-sol 系 | フロンティアモデルの明示的オーバーライド |
OMX_DEFAULT_SPARK_MODEL | gpt-5.6-luna 系 | スパーク/低複雑度モデルのデフォルト |
OMX_TEAM_WORKER_MCP_COMPAT | off | チームワーカーで MCP 無効化を抑止する互換オプトイン（1 / true） |
公式・ドキュメント・コミュニティ
- GitHub: Yeachan-Heo/oh-my-codex — 本体リポジトリ
- npm: oh-my-codex — パッケージ（
npm i -g oh-my-codex） - 公式 Website
- サイト内ドキュメント: Getting Started · Agents · Skills · Integrations
- OpenClaw 連携ガイド（リポジトリ内ドキュメント）
- Discord コミュニティ
- OpenAI Codex CLI — 実行エンジン本体
- oh-my-claudecode — Claude Code 向け姉妹プロジェクト