oh-my-codex (OMX)

npm install -g oh-my-codex  ·  OpenAI Codex CLI のワークフロー強化レイヤー

プロジェクト概要

OMX は Codex CLI を置き換えない。Codex を実行エンジンとして維持しながら、再利用可能なロール・ワークフロースキル・永続状態管理を追加するレイヤーです。

40
Skills
30
Agent Prompts
4
MCP Servers
11+
CLI Commands
1 — 概要
3 層メンタルモデル

OMX の構成要素はシンプルな 3 層で理解できます。

L1
Codex CLI（実行エンジン）
エージェントの実際の作業を担当。OMX に置き換わらない。
L2
OMX ロールキーワード & スキル
$architect / $plan / $team などの再利用可能なワークフローを提供。
L3
.omx/ — 永続状態ストレージ
プラン・ログ・メモリ・モード状態をセッションをまたいで保持。
OMX の用途
  • Codex をそのまま使いながら より強力なデフォルト起動（omx --madmax --high）
  • $architect / $executor などの 再利用可能なロール呼び出し
  • $plan / $ralph / $team などの 再利用可能なワークフロー
  • スコープ付き AGENTS.md による プロジェクト固有ガイダンス
  • プラン・ログ・メモリ・モード追跡のための 永続状態（.omx/）
いつ OMX は不要か？ Codex をワークフローレイヤー無しで使いたい場合。OMX は付加レイヤーであり、Codex の代替ではありません。
2 — クイックスタート
前提条件
依存バージョン用途
Node.js20+OMX のランタイム
@openai/codex最新実行エンジン（CLI）
OpenAI API Key—Codex の認証
tmux任意チームモード（macOS/Linux）
psmux任意チームモード（Windows ネイティブ）
推奨インストールフロー
Step 1
インストール
Codex CLI と OMX を npm でグローバルインストール。
Step 2
omx setup
プロンプト・スキル・config・AGENTS.md を自動インストール。
Step 3
omx doctor
インストールを検証。9 項目のチェックがすべて OK になることを確認。
Step 4
omx --madmax --high
推奨設定で Codex CLI を起動。$architect や $plan で作業開始。
# 1. インストール
npm install -g @openai/codex oh-my-codex

# 2. セットアップ（プロンプト 30 本・スキル 40 本をインストール）
omx setup

# 3. インストール検証（9 項目 OK を確認）
omx doctor

# 4. 推奨起動
omx --madmax --high

# セッション内で役割・ワークフローを呼び出す
$architect "analyze the authentication flow"
$plan "map the safest implementation path"
omx setup の出力（参考） 
[1/7] Creating directories...         Done.
[2/7] Installing agent prompts...     Installed 30 agent prompts.
[3/7] Installing skills...            Installed 40 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.
3 — スキル & ロール
呼び出し規則
  • $name でワークフロースキルまたはロールキーワードを起動
  • /skills でインストール済みスキルを一覧表示
  • キーワードは大文字小文字を区別しない。メッセージ内のどこにあってもマッチ。
  • 複数のキーワードが同時にマッチした場合は最も具体的なものを使用。
キーワードルーティング（主要スキル）
キーワードスキル概要
ralph, don't stop$ralph完了まで実行を継続する持続的実行ループ
autopilot, build me$autopilot要件分析→設計→実装→QA の完全自律パイプライン
ultrawork, parallel$ultrawork並列エージェントによる大規模作業
plan this, let's plan$plan実装前の計画ワークフロー
interview, don't assume$deep-interviewSocratic インタビュー（Ouroboros）で要件確認
ralplan, consensus plan$ralplanRALPLAN-DR 構造的合意計画
team, swarm$teamtmux ベースのマルチエージェント並列実行
analyze, investigate$analyze深層分析・調査
ecomode, budget$ecomodeトークン効率モード
tdd, test first$tddテスト駆動開発ワークフロー
code review$code-reviewコードレビュー
security review$security-reviewOWASP Top 10 セキュリティ監査
cancel, stop$cancelアクティブモードを終了
ロールカタログ（主要 6 ロール）
ロール複雑度主な用途
exploreLow高速コードベース探索・パターン検索
plannerStandard作業計画とシーケンス構築
architectHigh読み取り専用分析・診断・トレードオフ評価
debuggerStandard根本原因分析
executorStandard→High実装・リファクタリング（実装作業のデフォルト）
verifierStandard完了証拠収集・バリデーション

専門ロール（dependency-expert、style-reviewer 等）はスキル/キーワードルーティング経由で利用可能。

使用例 
# 分析→計画→実行の典型的フロー
$architect "analyze the authentication flow"
$plan "map the safest implementation path"
$executor "implement the planned changes"
$verifier "check all tests pass"

# 大規模タスクへのエスカレーション
$ralph "keep implementing until all tests pass"
$team 3:executor "fix all TypeScript errors in parallel"

# 要件が曖昧な時は deep-interview でスコープを確定
$deep-interview "gather requirements for new API"
4 — チームランタイム
チームモードの概要

チームモードは tmux ベースのマルチエージェント実行環境です。複数の Codex/Claude ワーカーを1つの tmux セッション内に並列起動し、共有タスクキューで協調させます。

利用タイミング： tmux/ワークツリーによる持続的協調が価値をもたらす場合のみ使用。 デフォルトの作業開始方法として使うのは推奨されない。オーバーヘッドに見合う場合に限る。
チームパイプライン
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-statusin_progress → completed 等に状態遷移
通知send-message / broadcastワーカー間のメッセージパッシング
確認get-summaryJSON エンベロープ（schema_version 1.0）でステータス取得
プラットフォーム別 tmux インストール
プラットフォームコマンド
macOSbrew install tmux
Ubuntu/Debiansudo apt install tmux
Fedorasudo dnf install tmux
Archsudo pacman -S tmux
Windowswinget install psmux
Windows (WSL2)sudo apt install tmux
5 — アーキテクチャ
リポジトリ構成 
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/    # 読み取り専用リポジトリ探索
│   ├── omx-sparkshell/ # ノイズ削減シェルラッパー
│   ├── omx-runtime/    # Rust ランタイムコア
│   ├── omx-runtime-core/ # コアライブラリ
│   └── omx-mux/        # tmux マルチプレクサバインディング
├── skills/          # 40 スキル（SKILL.md 形式）
├── prompts/         # 30 エージェントプロンプト（*.md）
├── missions/        # オートリサーチミッション定義
├── playground/      # リサーチショーケースハブ
├── AGENTS.md       # オーケストレーションブレイン（自動生成）
└── package.json
.omx/ 永続状態
パス内容
.omx/state/モード状態（ralph・team・autopilot 等）
.omx/notepad.mdセッションメモ（notepad_write_working MCP）
.omx/project-memory.jsonクロスセッションプロジェクトメモリ
.omx/plans/PRD・テストスペック（ralph 実行ゲート）
.omx/logs/実行ログ
4 つの MCP サーバー
サーバー提供ツール
omx_state状態読み書き・チームメッセージング（team_send_message, team_broadcast, mailbox 系）
omx_memoryプロジェクトメモリ・ノートパッド
omx_code_intelコードインテリジェンス（シンボル・パターン検索）
omx_trace実行トレース・デバッグログ
Rust コンポーネントの役割
クレート役割呼び出し方
omx-explore読み取り専用のリポジトリ探索。ファイル・シンボル・パターン検索に特化。omx explore --prompt "..."
omx-sparkshellノイズの多い読み取り専用コマンドをコンテキスト効率よく実行。omx sparkshell <command>
omx-muxtmux セッション管理・ペイン操作バインディング。チームランタイム内部
omx-runtimeRust ランタイムコア。内部
omx-runtime-coreコアライブラリ（omx-runtime が依存）。内部
6 — コマンドリファレンス
CLI コマンド一覧
コマンド説明
omx / omx --madmax --highCodex CLI を推奨設定で起動（メインエントリ）
omx setupプロンプト・スキル・config.toml・AGENTS.md を一括インストール
omx setup --force既存 AGENTS.md を上書きして再インストール
omx doctorインストール状態を 9 項目で検証
omx versionバージョン・Node.js バージョン・プラットフォームを表示
omx statusアクティブなモードをすべて表示
omx cancelアクティブなモードをキャンセル
omx team <N>:<role> "task"N ワーカーのチームを起動（役割: executor 等）
omx team status <name>チームのタスク分配・ワーカー状態を確認
omx team resume <name>中断したチームを再開
omx team shutdown <name>チームを正常終了・状態クリーンアップ
omx team api <op> --input '{...}' --jsonCLI インターオップ経由でタスク/メッセージ操作
omx explore --prompt "..."読み取り専用リポジトリ探索（Rust バックエンド）
omx sparkshell <cmd>ノイズ削減シェルコマンド実行
omx hud --watchHUD 監視ビューを起動
omx reasoning推論設定管理
環境変数（チームモード）
変数デフォルト説明
OMX_TEAM_WORKER_CLIautoワーカー CLI の選択モード
OMX_TEAM_WORKER_CLI_MAP自動生成ワーカーごとの CLI 割り当て（カンマ区切り）
OMX_TEAM_WORKER_LAUNCH_ARGS-c model_reasoning_effort="low"ワーカー CLI に渡す起動引数
OMX_DEFAULT_FRONTIER_MODEL現行フロンティアフロンティアモデルの明示的オーバーライド
OMX_DEFAULT_SPARK_MODEL低複雑度デフォルトスパークモデルのデフォルト
参考リンク