oh-my-codex入門 — Codex CLIをチーム開発ワークフローに変える拡張レイヤー

はじめに

Codex CLI は優秀な単体 assistant だが、実際のチーム開発で使い込むと壁にぶつかる。タスクの分割と割り当てを毎回手動で行う必要がある、セッションを閉じると計画やログが消える、複数のエージェントを協調させる組み込みの仕組みがない——これらは CLI 単体の設計思想では解決しにくい問題だ。

oh-my-codex（以下 OMX）は、この「単体 assistant の限界」を上位レイヤーで解決するために作られた。2026年4月時点で ~2.2万 stars を集めている。

本記事では OMX のアーキテクチャと導入手順を実践的に解説する。姉妹プロジェクトである oh-my-claudecode 入門、および両ツールの設計判断を比較した oh-my-claudecode vs oh-my-codex も合わせて参照してほしい。

注記: 本記事の情報は2026年4月時点のものであり、各リポジトリの機能・数値は変動する可能性がある。Stars 数は2026年4月13日時点（gh api）に基づく。最新の情報は各リポジトリの README を参照してほしい。

oh-my-codex とは

重要な前提として、OMX は Codex CLI を置き換えない。Codex CLI の上にワークフロー層を被せる拡張レイヤーだ。タスクルーティング、ワークフロー管理、チーム実行ランタイムの3つを Codex CLI に追加することで、「単体 assistant」を「ワークフローエンジン」に変える。既存の Codex CLI の設定やカスタマイズはそのまま活かせる。

OMX の姉妹プロジェクトである oh-my-claudecode（以下 OMC）は、同じ作者 Yeachan-Heo 氏による Claude Code 向けの拡張レイヤーだ。明確化→計画→実行の3段階ワークフロー、tmux を使った並列実行、HUD によるリアルタイム状態表示など、両ツールの設計には多くの共通点がある。一方で、SDK 統合の深度やエージェント定義のアーキテクチャには意図的な差異もある。その分析は oh-my-claudecode vs oh-my-codex に委ねる。

README は v0.12.5 時点で16言語（docs/readme/ で確認）で提供されており、macOS / Linux に最適化されている。

アーキテクチャ

TypeScript + Rust ハイブリッド構成

OMX はメインロジックを TypeScript で実装し、パフォーマンスが要求される処理を Rust クレートで補完するハイブリッド構成を採る（v0.12.5 時点）。

TypeScript 側（src/ ディレクトリ、v0.12.5 時点で221本の本番ファイル）にはワークフロー全体を支える主要モジュールが揃っている。src/team/ がチームランタイム（runtime.ts は4,450行）、src/hooks/ がフック統合、src/hud/ がステータス表示、src/mcp/ が MCP サーバー群、src/ralph/ が永続実行ループ、src/ralplan/ がコンセンサス計画を担う。src/autoresearch/ や src/openclaw/ など、ワークフロー拡張のためのモジュールも多数存在する。

Rust 側（crates/）は5クレート構成だ。コードベース検索（omx-explore）、tmux 抽象化（omx-mux）、実行ランタイムコア（omx-runtime-core / omx-runtime）、シェルネイティブ検査（omx-sparkshell）を担う。TypeScript だけではパフォーマンスや OS 操作の面で難しい処理を、Rust クレートが補っている。

軽量な本番依存設計

OMX の特徴的な設計判断のひとつが、本番 npm 依存の最小化だ。package.json の dependencies は3パッケージのみに絞られている。

{
  "dependencies": {
    "@iarna/toml": "^2.2.5",
    "@modelcontextprotocol/sdk": "^1.26.0",
    "zod": "^4.3.6"
  }
}

@iarna/toml は Codex の config.toml 読み書き用、@modelcontextprotocol/sdk は MCP サーバー構築用、zod はスキーマバリデーション用だ。ビルドツール（Biome、TypeScript）やテストツール（c8）はすべて devDependencies に分離されており、実行時依存を最小化している。

MCP サーバー4つ

OMX は Model Context Protocol サーバーを4つ内蔵しており、omx setup 実行時に Codex CLI の MCP 設定へ自動登録される。

• state-server: ワークフローモード状態の CRUD（.omx/state/{mode}-state.json に永続化）
• memory-server: プロジェクトメモリ（.omx/project-memory.json に永続化）
• trace-server: 実行トレース記録
• code-intel-server: コードインテリジェンス

各サーバーは @modelcontextprotocol/sdk の stdio トランスポートで起動し、エージェントがワークフロー状態やプロジェクトメモリを MCP ツール経由で参照・更新できる（src/mcp/state-server.ts で実装確認済み）。

フック統合

OMX のフックは、Codex ネイティブフックとOMX プラグインフックの二重レイヤーで構成される。この構造が OMX の拡張性の核心だ。

Codex ネイティブフック（.codex/hooks.json 経由）は、Codex CLI のフック機構を利用してセッションのライフサイクル全体にカスタム処理を差し込む。SessionStart でセッション開始処理と .omx/ の gitignore 設定が行われ、UserPromptSubmit でマジックキーワード（$ralph、$team 等）を検出してスキルを起動し、状態を永続化する。PreToolUse / PostToolUse では Bash コマンドのインターセプトが行われ、Stop イベントで Ralph / Autopilot / Team 等の継続判定が行われる。

OMX プラグインフック（.omx/hooks/*.mjs）は、ユーザーが独自フックを追加できる拡張ポイントだ。HookPluginSdk が提供するインターフェースを通じて、tmux 操作、ログ出力、状態の読み書き、OMX セッション情報にアクセスできる。v0.12.5 時点で17種の名前付きイベントが定義されている（src/hooks/extensibility/types.ts の HookEventName 型より）。

session-start / stop / session-end / session-idle / turn-complete
blocked / finished / failed / retry-needed / pr-created
test-started / test-finished / test-failed
handoff-needed / needs-input / pre-tool-use / post-tool-use

フックファイルは .omx/hooks/ ディレクトリに .mjs 形式で配置する。HookEventEnvelope 型（schema_version, event, source, context, session_id 等のフィールドを持つ）でイベントが渡されるため、プラグイン側で細かい条件分岐が書ける。

Codex CLI のネイティブ機構をそのまま活かしつつ、OMX 独自の拡張層を重ねるこの設計は、既存の Codex 設定を壊さずに機能を追加できるという利点をもたらしている。

スキルとワークフロー

スキルカタログとロールプロンプト

OMX は v0.12.5 時点で36種のスキルと33種のロールプロンプトを提供している（ls skills/、ls prompts/ で確認）。

スキルは skills/ ディレクトリに SKILL.md 形式で定義されており、$ プレフィックスのマジックキーワードで呼び出す。後述のワークフローを構成する4つの主要スキルに加え、$autopilot（ユーザー承認なしの自律実行）、$autoresearch（自律リサーチ）、$ultrawork（高強度タスク実行）、$ultraqa（高品質 QA）、$code-review、$tdd、$security-review、$deepsearch など、多様な用途に対応したスキルが揃っている。

ロールプロンプトは prompts/ ディレクトリに格納されており、$team 起動時にタスク内容から動的に選択されるプロンプトカタログとして機能する。analyst.md、architect.md、debugger.md、qa-tester.md、product-manager.md など、33種のロールが用意されている。これらはエージェントの事前定義ではなく、「タスクにどの視点で向き合うか」を設定するものだ。

ワークフロー: 明確化 → 計画 → 実行

OMX が提供する中心的なワークフローは3段階で構成される。以下のコマンドは omx --madmax --high で起動したセッション内で使用する。

第1段階: $deep-interview（明確化）

タスクの境界を明確にするところから始まる。$deep-interview を実行すると、OMX がタスクの曖昧な部分を対話的に洗い出す。影響範囲、既存のテスト、非機能要件などを確認する質問を通じて、後続の計画フェーズに必要な情報を構造化する。

$deep-interview "認証機能のリファクタリング"

第2段階: $ralplan（計画）

明確化された要件をもとに実行計画を立案する。タスクの分割、依存関係、各タスクの担当エージェント割り当てが含まれる計画が生成され、.omx/plans/ に保存される。ユーザーの承認を経て次のステップに進むが、承認前に計画を修正することも可能だ。

$ralplan

第3段階: $ralph または $team（実行）

実行フェーズでは、タスクの性質に応じて2つのモードを選択する。

$ralph は単一エージェントが計画全体を逐次実行するモードだ。タスク間の文脈を保持しやすく、依存関係が複雑な場合に適している。$team は複数エージェントが独立したタスクを並列処理するモードで、互いに依存しないタスクが多い場合に実行時間の短縮が期待できる。

# 単一永続実行
$ralph

# 並列チーム実行
$team

$team モードでは tmux のセッション管理により、各エージェントの実行状況を個別に監視・操作できる。

可観測性と運用

HUD（ヘッドアップディスプレイ）

HUD は「エージェント個別のタスク一覧」を表示するダッシュボードではなく、セッション全体のステータスをコンパクトに表示するステータスラインだ。--watch モードで1秒ごとにポーリング更新し、--tmux オプションで tmux の split-window に自動展開できる。

表示要素は、git ブランチ名、Ralph 進捗（ralph:3/10）、チームワーカー数（team:3 workers）、各モードの状態（Ultrawork / Ralplan / Deep-interview / Autoresearch / UltraQA / Autopilot）、ターン数、トークン数、クォータ使用率、セッション経過時間、最終アクティビティ時刻、累積ターン数だ（src/hud/render.ts の Element Renderer 群より確認）。

表示密度は minimal（基本状態のみ）、focused（トークン・クォータ・経過時間を追加）、full（全要素）の3プリセットから選択できる。

.omx/ ディレクトリ構造

OMX はプロジェクトの計画・ログ・状態を .omx/ ディレクトリに永続化する。セッションをまたいだ作業の継続を支える基盤だ。src/utils/paths.ts の各パス関数から確認できる主なパスを挙げる。

• .omx/state/ — ワークフローモード状態（MCP state-server 経由）
• .omx/plans/ — $ralplan が生成した計画アーティファクト
• .omx/logs/ — セッションログ
• .omx/notepad.md — セッション間メモ
• .omx/project-memory.json — プロジェクトメモリ（MCP memory-server 経由）
• .omx/hooks/ — ユーザー定義プラグインフック（*.mjs）

.omx/ は omx setup 実行時と SessionStart フック処理時の両方で .gitignore に自動追加される。plans/ をコミットしてチームで共有したい場合は、.gitignore から除外する運用も可能だ。

エージェントチーム（マルチ CLI 対応）

$team モードの特徴のひとつは、ワーカーとして起動できる CLI が Codex CLI に限られない点だ。src/team/tmux-session.ts の TeamWorkerCli 型定義が示すように、v0.12.5 時点で Codex / Claude / Gemini の3 CLI をワーカーとして扱える。

export type TeamWorkerCli = 'codex' | 'claude' | 'gemini';

$team モードでは各ワーカーに独立した作業ディレクトリを提供するため、git worktree を活用する（src/team/worktree.ts で実装）。これによりワーカー間のファイル変更干渉がなく、真の並列実行環境が構築される。

タスク分配は src/team/state.ts のタスクキューが claim / release / reclaim パターンで行い、チームのフェーズは src/team/orchestrator.ts が team-plan → team-prd → team-exec → team-verify → team-fix の順で管理する。tmux セッション上でワーカーを起動するため、SSH 切断後もエージェントが動き続ける耐久性がある。

導入手順

前提条件

• Node.js 20 以上（package.json の "engines": {"node": ">=20"} より）
• Codex CLI がインストール済みであること
• tmux（$team モードを使う場合）

インストール

npm install -g @openai/codex oh-my-codex

初期設定

omx setup

omx setup はプロジェクトルートに .omx/ ディレクトリを作成し、初期設定ファイルを配置する。Codex CLI のフック設定と MCP サーバー設定も自動で追加される。

推奨フローでの起動

omx --madmax --high

--madmax は Codex CLI の承認確認とサンドボックスをバイパスし（--dangerously-bypass-approvals-and-sandbox のエイリアス）、エージェントが自律的に操作を実行できるようにする。安全機構を無効化するため、信頼できる環境でのみ使用すること。--high は高品質モードで実行する。

向いているケース / 向かないケース

向いているケース

• チーム開発でロール分担が必要な場合: フロントエンド、バックエンド、テストなどの役割を異なるエージェントに割り当て、並列で進めたい
• 複数の CLI エージェントを混在させたい場合: Codex / Claude / Gemini CLI をワーカーとして組み合わせた構成が必要な場合
• 中〜大規模のリファクタリング: 計画フェーズで全体像を整理し、段階的に実行することで手戻りを減らせる
• 長時間稼働するタスク: tmux ベースの耐久性により、SSH 切断後もエージェントが動き続ける
• 繰り返しの多いプロジェクト: .omx/ に蓄積された計画・ログ・プロジェクトメモリ（MCP 経由）が次回以降のタスク設計に活用できる
• カスタムフックでワークフローを拡張したい場合: .omx/hooks/*.mjs でプラグインフックを追加し、独自の自動化を組み込める

向かないケース

• 単発の小さなタスク: 「このファイルのバグを直して」程度なら Codex CLI を直接使ったほうが早い。OMX のワークフローはオーバーヘッドになる
• Codex CLI 自体に不慣れな段階: OMX は Codex CLI の上位レイヤーなので、まず Codex CLI 単体での運用に慣れてから導入すべきだ
• Windows 環境: macOS / Linux に最適化されており、Windows は tmux の代わりに psmux を使う二次パス対応にとどまる

まとめ

oh-my-codex は、Codex CLI を「単体の assistant」から「ワークフローエンジン」に変える拡張レイヤーだ。

TypeScript と Rust 5クレートのハイブリッド構成を採りながら、本番 npm 依存を3パッケージに絞った軽量設計が特徴といえる。フック統合の二重レイヤー（Codex ネイティブフック + OMX プラグインフック）はカスタマイズの自由度を高め、MCP サーバー統合によって状態・メモリ・トレースにエージェントが構造化アクセスできる点は単純なスクリプトラッパーとは一線を画す。$team モードのマルチ CLI ワーカー（Codex / Claude / Gemini）と git worktree による並列環境、HUD によるステータス監視、1:1 対応のテスト体制を含む CI 構成も、本番利用を意識した設計から来ている。

単発タスクには不要だが、チームで継続的に AI エージェントを活用したい場合は導入を検討する価値があるだろう。OMC との設計判断の違いや選択軸については oh-my-claudecode vs oh-my-codex を参照してほしい。

参考リンク

• oh-my-codex（GitHub） — Codex CLI 向け拡張レイヤー
• oh-my-codex 公式サイト — ドキュメント・ガイド
• oh-my-claudecode 入門（Qiita） — Claude Code 向け姉妹プロジェクトの詳細
• oh-my-claudecode vs oh-my-codex（Qiita） — 設計判断の違いと選択軸
• Codex CLI（GitHub） — OpenAI 公式のコーディングエージェント CLI
• Model Context Protocol — MCP 公式ドキュメント