oh-my-codex (OMX) 入門｜Codex CLIにエージェントチームとHUDを乗せるワークフロー層

oh-my-codex（OMX） は、OpenAI Codex CLIの上に「定型ワークフロー」「役割キーワード」「tmuxベースの永続ランタイム」「.omx/配下の永続状態」を被せるワークフロー層だ。リポジトリ Yeachan-Heo/oh-my-codex は2026年2月に公開され、わずか3ヶ月で27,684スター・2,228フォークを集めている（2026-05-06時点）。Codex本体を置き換えるのではなく、$deep-interview $ralplan $ralph $team $ultragoal といった役割キーワードでCodexの実行を構造化し、.codex/hooks.json のネイティブフックや .omx/ ディレクトリの永続状態と組み合わせて「Codex運用の再現性」を担保する設計になっている。

Codex CLI全体の使い方は OpenAI Codex CLI完全ガイド2026｜AGENTS.md・3つの承認モード・Claude Code比較を1記事で網羅 を参照してほしい。本稿はその上で「Codexを業務的に回す」ことに絞る。

30秒で理解するoh-my-codex（OMX）：何を「足す」のか

OMXが日常的なCodex運用に追加するものは、ざっくり4階層に整理できる。

公式READMEの表現を借りると OMXは Codexを置き換えない 。Codexは実行エンジンとして残し、OMXは「使い始め」と「使い続ける時の手数」を構造化する。スター履歴も2026年2月公開→4月時点で2万超→5月で約2.7万と急峻で、OpenAI Codex CLIエコシステムにおける運用ハーネス系OSSの代表格になりつつある。

検証環境: macOS 14.5 / Node.js 20 / Codex CLI最新 / oh-my-codex v0.4.x系（2026-05-06時点のmain）。omx doctor および omx exec --skip-git-repo-check -C . "Reply with exactly OMX-EXEC-OK" までの動作確認。各スキルの仕様は公式README・docs（docs/agents.html docs/skills.html docs/codex-native-hooks.md）に基づく。

アーキテクチャ：Codex CLI + OMXランタイム + .omx/ の三層構造

OMXがどこに何を差し込んでいるかを1枚の図で押さえる。Codex本体・OMXランタイム・ユーザーディレクトリの三層に分けると、各機能の責務がはっきりする。

ポイントは3つ。

1. Codex本体には触らない。codex login / ~/.codex の設定はそのまま使い、OMXは .codex/config.toml と .codex/hooks.json に自分が管理する区画を持つ。omx uninstall でOMX管理ラッパーだけ綺麗に剥がせる。
2. tmuxが第一級ランタイム。omx --madmax --high をmacOS/Linuxの対話的端末で起動すると、リーダーCodexはOMX管理のdetached tmuxの中で立ち上がり、HUDとruntimeペインが横に並ぶ。Codexアプリやtmuxなしの素のシェルは--direct扱いになる。
3. .omx/ がチームメモリ。$ralplan の承認済みプランは .omx/plans/ 配下に、$ultragoal は .omx/ultragoal/ 配下に、wikiは .omx/wiki/ 配下に永続化される。新しいセッションを開いてもOMXがこのディレクトリを再注入するため、/clear してもプロジェクトコンテキストが溶けない。

Codexプラグインレイアウトとセットアップの違い

最近のOMXは plugins/oh-my-codex というCodex公式プラグインレイアウトも同梱している（.agents/plugins/marketplace.json にメタデータ）。プラグインインストールはCodexのプラグインキャッシュ（${CODEX_HOME:-~/.codex}/plugins/cache/$MARKETPLACE_NAME/oh-my-codex/$VERSION/）に置かれ、ミラーされたスキル群とプラグインスコープのMCPサーバ・アプリ・コンパニオンメタデータが入る。ただしネイティブ/ランタイムフックはプラグインマニフェスト側ではなくセットアップ側に残るため、プラグイン経由インストールはnpm install -g oh-my-codex + omx setup の代替にはならない、というのが公式の整理だ。Discord(VencordやBetterDiscord) や Slack(BetterSlack) のような「ローダー型のElectron改造」とは設計思想が違い、こちらはCodex本体を尊重するワークフロー追加という位置づけになっている。

5つの中核スキル：$deep-interview → $ralplan → $ralph / $team → $ultragoal

OMXのスキルは43本ある（skills/ 配下）が、日々の運用で使うのはほぼ次の5つに収束する。それぞれがワークフローのフェーズに対応している。

$deep-interview：要件のクラリファイ

「あいまいなままCodexに投げる」のがいちばん事故るパターンなので、それを防ぐためのインタビュー型スキル。出力はスコープ／非ゴール／前提条件／成功条件の4点で、これを $ralplan のインプットにする運用が公式推奨だ。

$deep-interview "clarify the authentication change"

$ralplan：承認可能な計画への変換

$ralplan は計画レビュー特化のスキル。アーキテクチャ案・トレードオフ・代替案を提示し、人間が「この案で進める」と一度だけGOを出すためのインターフェースになっている。承認済みプランは .omx/plans/ 配下にYAML/Markdownで保存され、後段のスキルが必ずこれを参照する。

$ralph：一人で持ち切るループ

$ralph はOMXの中で最も古典的な「Codexを自律ループで回す」スキル。承認済みプランを起点にして、コード生成→検証→次の課題の摘出→修正、を一人のCodexが持ち切る。AI Heartlandでは別エコシステムの自律ループOSSとして Ralph：Claude Codeを自律ループで動かすハーネスエンジニアリングOSS｜15,000スター を解説しているが、思想的に近い。OMXの$ralph はCodex CLI上で同じ系譜の体験を提供する。

$team：worktree×tmuxの並列実行

$team は 3:executor のような <size>:<role> 構文で、worktreeとtmuxを掛け合わせた並列Codex実行を起動する。それぞれのワーカーは別のworktreeで作業し、結果を統合する。落ちたチームは omx team status omx team resume omx team shutdown で観測・回復・破棄でき、CIっぽく実行の単位を後追いで再現できるのがミソ。

$ultragoal：複数Codexゴール跨ぎの耐久ハンドオフ

「ローンチ」のような連続するCodexゴールを .omx/ultragoal 配下のアーティファクトに分解する。分割された個別ゴールは $ralplan → $ralph/$team の通常フローで消化され、フェーズが切り替わるたびに次のフェーズへのハンドオフ要約が生成される。Codexの単一セッションが扱える範囲を超える長期プロジェクトを「複数の有限セッション」に変える仕組みだ。

インストール手順：npm i -g から omx --madmax --high まで

公式が推奨するのは「グローバルnpm + 最大プロファイル起動」。日本語環境のzshでも特殊なPATH調整は不要だ。

# 1) グローバルインストール
npm install -g @openai/codex oh-my-codex

# 2) セットアップ（プロンプト/スキル/AGENTS.md/.codex/config.toml/.codex/hooks.json）
omx setup

# 3) ヘルスチェック
omx doctor

# 4) 「実際にモデルが叩けるか」のスモークテスト
codex login status
omx exec --skip-git-repo-check -C . "Reply with exactly OMX-EXEC-OK"

# 5) 推奨デフォルトで起動
omx --madmax --high

ここで重要なのは 「omx doctor が緑だからといって動くとは限らない」 という公式の注意書き。omx doctor はOMX側のファイル整合性しか見ない。認証・プロファイル・openai_base_url が壊れているケースは omx exec の実テストでしか拾えないため、ローカルプロキシ経由（OpenAI互換API）で運用している人は特に codex login status と omx exec をワンセットで通すのが安全だ。

omx setup が触るファイル

起動ポリシーの3モード

omx の起動モードは環境変数 OMX_LAUNCH_POLICY または CLI フラグで制御できる。tmuxを噛ませたくない場合は --direct 系を使う。

# 環境変数で固定（zshrc/bashrc に書くと永続）
export OMX_LAUNCH_POLICY=direct  # tmux/HUDなしで即起動

# CLIフラグは環境変数より強い（最後のフラグが勝つ）
OMX_LAUNCH_POLICY=direct omx --tmux --yolo  # → tmux モードで起動

# 自動判定に戻す
unset OMX_LAUNCH_POLICY

auto（既定） / tmux / detached-tmux / direct の4種があり、Codexアプリ内・tmuxペイン内などの起動文脈を見てOMXが妥当なモードを選ぶ。CIなど非対話環境では direct を明示するのが事故が少ない。

ネイティブCodexフック：OMXのライフサイクル割り込みポイント

Codex CLIは2026年に入ってからネイティブフック機構を整備しており、OMXはそれを最大限に活用する側として実装されている。.codex/hooks.json に登録されるOMX管理ラッパーの中で、現在ネイティブにサポートされているのは次の通り。

OMXのフック設計は 「ネイティブが使えるならネイティブ、ないならtmux/notify-hook/derived watcher にフォールバック」 という階層構造になっており、docs/codex-native-hooks.md に現時点のフォールバック行列が随時更新されている。Lore commitの強制が邪魔な人は、.codex/config.toml に次の1行を足せばPreToolUseの安全チェックを残しつつコミット規約だけ無効化できる。

[shell_environment_policy.set]
OMX_LORE_COMMIT_GUARD = "0"

.omx/hooks/*.mjs にはOMXプラグイン側のフックが置かれ、ネイティブフックの後段でOMX固有の振る舞い（HUD更新、ralphループの継続判断など）を実装している。素のCodex運用しか知らないと「フックがどこで何をしているか」を見失いがちなので、トラブル時は .codex/hooks.json と .omx/hooks/ の両方を見るのがセオリー。

運用支援サーフェス：team / wiki / explore / sparkshell

中核ワークフローの外側で、OMXは運用専用のCLIを3つ持っている。日常で頻繁に使うのは team・wiki・explore あたりだ。

omx team：tmux+worktreeの並列ランタイム

$team をシェル側から直接叩くサーフェス。Codexアプリやtmuxの外で omx team を起動すると、結局tmuxセッションを生やして並列実行を始めるので、Codexアプリ内ではなくOMX CLIから触るのが推奨されている。

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>

ハマる代表例は「死んだチームが resume_blocker 表示で残る」パターン。次の3コマンドで安全に綺麗にできる。

omx team shutdown <team-name> --force --confirm-issues
omx cancel
omx doctor --team

omx wiki：プロジェクト固有のmarkdown wiki

.omx/wiki/ 配下にmarkdown-firstかつsearch-firstの知識ベースを持てる。ベクトル検索ではなく素のmarkdown＋全文検索なので、Gitに乗せたまま運用できる。MCPサーバとしても露出しており、Codex本体・他のAIクライアントから検索できる。

omx wiki list --json
omx wiki query --input '{"query":"session-start lifecycle"}' --json
omx wiki lint --json
omx wiki refresh --json

omx explore / omx sparkshell：低コスト調査の二刀流

explore はリポジトリ読み取り専用の調査エージェント、sparkshell はシェルネイティブな検査と境界付き検証を提供する。.omx/wiki/ がある場合、omx explore はwikiコンテキストを優先して注入し、足りなければ広範なリポジトリ検索にフォールバックする。フォールバックの境界はstdout/stderrに明示的に出るため、コスト挙動が普段と違うときに即座に気付ける設計になっている。

omx explore --prompt "find where team state is written"
omx sparkshell git status
omx sparkshell --tmux-pane %12 --tail-lines 400

似たOSSとの位置づけ：Ralph・OpenClaw・Codex++との違い

「AIコーディングエージェントを業務で回すための層」を提供するOSSはここ半年で急増している。代表的なものとOMXの違いを整理しておく。

OMXは「ワークフロー＋ランタイム＋永続状態」のフルセットを狙っている点で守備範囲が広い。Ralphの自律ループ思想を吸収した $ralph、OpenClaw連携用のドキュメント（OpenClaw guide）、Codex本体のUIには手を入れない方針——どれを取っても「Codex本体を尊重してその外側でアセンブルする」という設計思想で一貫している。

ハーネス系OSS全体の流れと選び方は OpenClaw完全ガイド2026｜Claude Code通知ゲートウェイの全機能 も参考になる。

ハマりどころ・運用上の注意点

公式README・トラブルシュートドキュメントから、実運用で踏みやすい罠を事前に押さえておく。

1. omx doctor 緑＝動くとは限らない

繰り返しになるが、omx doctor はOMXのインストール形状しか見ない。実認証は codex login status + omx exec --skip-git-repo-check -C . "Reply with exactly OMX-EXEC-OK" で確かめる。OpenAI互換プロキシを使っているとき、~/.codex/config.toml の openai_base_url がプロキシを向いていないと 401 Unauthorized / Missing bearer で落ちる。HOME・プロファイル・コンテナ・サービスシェルで ~/.codex の場所がズレているケースも頻出パターン。

2. Intel Macで syspolicyd / trustd のCPUスパイク

Intel Macでは omx --madmax --high の起動時にmacOS Gatekeeperが大量のプロセス起動を検証してsyspolicyd / trustdがCPUを食い切ることがある。対策は3つ。

# Quarantine属性を剥がす
xattr -dr com.apple.quarantine $(which omx)

# ターミナルアプリをDeveloper ToolsのallowlistにmacOS Security設定で追加

# 並列度を下げる（--madmax --high を避ける）
omx --high

3. Shift+Enter がtmux内でsubmitになる

OMX管理tmuxセッション内で Shift+Enter が改行ではなく送信になる場合、これはtmuxのextended-keyフォワーディング設定の問題。OMXは自前のCodex起動経路にextended-keyフォワーディングを既に有効化しているので、それでも発生する場合はターミナルアプリのcapabilityを疑うのがセオリー（公式 docs/troubleshooting.md 参照）。

4. ネイティブWindowsはセカンダリパス

ネイティブWindowsはサポート対象だが主要パスではなく、omx team のtmux相当には psmux（winget install psmux）が必要。WSL2＋Linux系tmux が公式推奨で、Windowsホストで本気で運用する人にとっては実質WSL2一択になる。

5. プラグインインストール ≠ セットアップインストール

Codexプラグインマーケットプレイス経由のインストールはミラーされたスキル群＋プラグインスコープのコンパニオンメタデータしか展開しない。ネイティブ/ランタイムフックは引き続きセットアップ管理なので、npm install -g oh-my-codex + omx setup を別途走らせる必要がある。プラグイン経由だけで済ませようとすると、SessionStart / Stop あたりのフックが効かず「ralphループが継続しない」「$team が再開しない」といった症状で悩むことになる。

まとめ：Codexを「日々のワークフロー」に変えるための層

oh-my-codex（OMX）は、Codex CLIをエージェントエンジンとしてそのまま尊重しつつ、上に 5つの中核スキル × tmuxランタイム × ネイティブhooks × .omx/ 永続状態 という4階層を被せる、現時点で最も野心的なCodex運用ハーネスだ。27,684スター・2,228フォーク・43スキルという数字が示すように、Codexエコシステムでの存在感は急速に大きくなっている。

最初の30分で押さえるべきは次の4つに尽きる。

1. インストール直後のスモークテスト：omx doctor で形状、omx exec で実認証
2. 5つの中核スキルの順序：$deep-interview → $ralplan → $ralph または $team → $ultragoal
3. 永続状態の場所：.omx/plans/ .omx/ultragoal/ .omx/wiki/ がプロジェクトのメモリ
4. フックの責務分担：ネイティブは .codex/hooks.json、OMX固有は .omx/hooks/*.mjs

「Codexを毎日使うが、毎回コンテキストを組み直しているのが辛い」段階に来たら、OMXは検討する価値がある。逆に「Codexにフックも永続状態も要らない、毎回素のCLIで十分」なら、READMEがはっきり書いている通り OMXは要らない。Codexを業務的に持ち切る人のための、明確に責務を切ったワークフロー層、というのが2026年5月時点の正しい位置づけだ。

参照ソース

• Yeachan-Heo/oh-my-codex（GitHubリポジトリ）
• oh-my-codex 公式ウェブサイト
• oh-my-codex docs/codex-native-hooks.md
• oh-my-codex docs/getting-started.html
• oh-my-codex docs/troubleshooting.md
• OpenAI Codex CLI（公式リポジトリ）