Codex JetBrains HUD + Hooks 導入ガイド

プロジェクトの背景：このアダプターは Claude Code v2.1.88 のリークされたソースコードの分析に基づいて作成されました。目的は、Codex に Claude Code と同様の能力を持たせ、JetBrainsシリーズのIDEで現在選択されているファイル、行番号、コード範囲を認識できるようにすることです。

Author: nealzhi

本ドキュメントでは、唯一の導入経路である HUD + hooks のみを扱います。

本リポジトリからは、古い「ローカルMCPサーバー + グローバルプロンプト」方式を削除しました。その方式は推奨しておらず、提供も終了しています。

1. 前提条件

以下の2つの条件を満たしている必要があります：

1. JetBrainsシリーズのIDEを使用していること 例：IntelliJ IDEA、PyCharm、WebStorm、GoLand、Android Studio

2. IDEに Claude Code 公式 JetBrains プラグイン がインストールされていること これが連携の前提です。このプラグインがないと、ローカルの ~/.claude/ide/*.lock や対応するローカルインターフェースが存在せず、Codexは現在選択中のファイルやコード範囲を読み取ることができません。

2. 依存関係のインストール

リポジトリのルートディレクトリで以下を実行します：

cd codex-jetbrains-mcp
npm install
brew install tmux

説明：

• npm install：HUDとhooksの依存関係をインストール

• tmux：HUDの依存先

3. HUDの導入

リポジトリのルートディレクトリで以下を実行します：

chmod +x codex-jetbrains-mcp/bin/codex-jetbrains-hud

今後 codex を実行する際に自動的にHUDを起動したい場合は、以下の行を ~/.zshrc または ~/.bashrc に追加してください：

alias codex='$(pwd)/codex-jetbrains-mcp/bin/codex-jetbrains-hud'

シェルを再読み込みします：

source ~/.zshrc

bash を使用している場合は以下を実行します：

source ~/.bashrc

macOS標準のターミナルやWarpターミナルでマウスホイールによるCodexウィンドウのスクロールができない場合は、以下のコマンドを実行して tmux のマウスサポートを有効にできます：

tmux set -g mouse on

HUDが起動すると、以下の行が表示されます：

JetBrains PyCharm 已连接 | test_main.py:2140-2147 (8 lines)

4. hooksの設定

このスキームの核心は以下の通りです：

1. codex 起動時にHUDを同時に起動する

2. HUDがJetBrainsの現在ファイル/行番号を自動的に .codex/jetbrains-selection-state.json に書き込む

3. UserPromptSubmit hookがメッセージ送信時にこの状態を読み取る

4. JetBrainsのコンテキストがある場合、「ファイルパス」または「ファイルパス + 行番号」のみを注入する

5. 選択されたテキスト自体は注入せず、Codexが必要に応じてファイルを読み取るようにする

4.1 推奨される起動方法

リポジトリのルートディレクトリで以下を実行します：

chmod +x codex-jetbrains-mcp/bin/codex-jetbrains-hud
alias codex='$(pwd)/codex-jetbrains-mcp/bin/codex-jetbrains-hud'

以降は通常通り codex を実行してください。

現在、codex-jetbrains-hud はHUDを表示するだけでなく、hookに必要な状態を自動的に同期します。これが唯一の推奨経路であり、個別の同期プロセスは不要であり、提供もしていません。

状態ファイルは以下に書き込まれます：

.codex/jetbrains-selection-state.json

4.2 hooksの設定

リポジトリには以下が含まれています：

• .codex/config.toml

• .codex/hooks/selection-state.mjs

• .codex/hooks.json

• .codex/hooks/user-prompt-submit-jetbrains-selection.mjs

導入方法は2通りあります：

1. このリポジトリディレクトリ内で codex を起動する場合 Codexはリポジトリ内の .codex/config.toml と .codex/hooks.json を直接読み取るため、追加のパス指定は不要です。

2. すでに独自のグローバルな ~/.codex/hooks.json を持っている場合 それを上書きせず、リポジトリ内の UserPromptSubmit 設定をマージしてください。 ~/.codex/hooks/ にコピーする場合は、エントリファイルだけでなく .codex/hooks/ ディレクトリ全体をコピーしてください。

.codex/config.toml の役割は、公式が要求するhooks機能のスイッチをオンにすることです：

[features]
codex_hooks = true

公式ドキュメントに従い、hooksはデフォルトで無効になっているため、config.toml で有効にするか、起動時に codex --enable codex_hooks を渡す必要があります。また、Codexの設定レイヤーは ~/.codex/config.toml とリポジトリ内の .codex/config.toml を合わせて読み取ります。プロジェクトが信頼済み（trusted）としてマークされていない場合、リポジトリレベルの .codex/config.toml は有効になりません。

リポジトリ付属の設定内容は以下の通りです：

{
  "hooks": {
    "UserPromptSubmit": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "node \"$(git rev-parse --show-toplevel)/.codex/hooks/user-prompt-submit-jetbrains-selection.mjs\"",
            "statusMessage": "Loading JetBrains selection"
          }
        ]
      }
    ]
  }
}

このhookは、UserPromptSubmit のたびにローカルの状態ファイルを読み取ります：

• ファイルのみが選択されている場合、Codexに「現在のファイル」を注入する

• コード範囲が選択されている場合、Codexに「現在のファイル + 行番号」を注入する

• JetBrainsのコンテキストがない、または状態が期限切れの場合は何も注入しない

コードテキストは注入せず、位置のガイドのみを行います。

4.3 古い設定のクリーンアップ

以前のバージョンを使用していた場合は、以下の2つを削除してください：

1. ローカルMCP設定の削除

codex mcp remove jetbrains-selection

2. 独自のグローバルプロンプト内の該当内容の削除

每次用户请求时，先调用 MCP 工具 jetbrains-selection.jetbrains_get_selection 获取 JetBrains 当前选区

この手順は必須です。そうしないと、モデルが古い思考プロセスに従って存在しないMCPツールを呼び出そうとする可能性があります。

4.4 hookが実際に注入する内容

ファイルのみを選択した場合、以下のような内容が注入されます：

JetBrains 当前选中文件：/path/to/file.ts
这只是文件指引，没有附带文件内容。
如果本轮问题和这个文件相关，请先自行读取该文件；如果无关，请忽略这条上下文。

コード行を選択した場合、以下のような内容が注入されます：

JetBrains 当前选中位置：/path/to/file.ts:120-146
这只是位置指引，没有附带代码内容。
如果本轮问题和这个位置相关，请先自行读取对应文件和行号；如果无关，请忽略这条上下文。

デフォルトの状態有効期限は 20s です。HUDの実行中、状態は 5s ごとに更新されます。HUDが終了すると、hookはすぐに古い状態の注入を停止します。環境変数 CODEX_JB_HOOK_MAX_AGE_MS を通じてこの時間を調整することも可能です。

5. なぜローカルMCP方式を廃止したのか

旧方式には主に以下の問題がありました：

• codex mcp add を別途実行する必要があり、インストールとメンテナンスのコストがかかる

• モデルがグローバルプロンプトに依存し、「毎ターン必ず一度MCPを呼び出す」ことを強制されるため、JetBrainsの選択範囲と無関係な質問でも無駄なステップが発生する

• 選択範囲が関連しているかどうかは本来現在の質問内容によって決まるべきであり、グローバルプロンプトに含めると動作が機械的になりすぎる

• ローカルMCPサーバーは中継層に過ぎず、実際にはClaude Code JetBrainsプラグインに接続する必要がある。この層を個別に維持するメリットは低く、複雑さが増す

• 古い設定のクリーンアップが困難で、移行後に無効なツール名や古いプロンプトが残りやすい

HUD + hooksに変更した後のメリットはより直接的です：

• メッセージ送信時にのみローカル状態を読み取るため、毎ターンMCP呼び出しが発生しない

• 注入内容はファイルパスや行番号のみであり、情報がクリーン。モデルが自分でファイルを読みに行くかどうかを判断できる

• 状態ファイルはプロジェクトルートごとに分離され、プロジェクトごとに .codex/jetbrains-selection-state.json が書き込まれる

• HUDが生存している間はハートビートが更新され、HUDが停止すると古い状態はタイムアウト後に自動的に無効化される

• 導入経路が単一化され、ユーザーはHUDとhooksのみをメンテナンスすればよく、MCP設定をメンテナンスする必要がない

6. 現在のスキームの仕組み

データリンクは以下の通りです：

1. Claude Code 公式 JetBrains プラグインがローカル接続情報と選択イベントを公開する

2. HUDが現在の作業ディレクトリに基づいて正しいJetBrainsプロジェクトウィンドウをマッチングする

3. HUDが選択範囲の変更を受け取ると、ファイルパス、行番号、ハートビート時間を現在のプロジェクトの .codex/jetbrains-selection-state.json に書き込む

4. UserPromptSubmit hookがメッセージ送信時にこの状態を読み取る

5. 状態が有効であれば、Codexに「現在のファイル」または「現在のファイル + 行番号」の軽量なプロンプトを注入する

このリンクにはローカルMCPサーバーは存在せず、追加のグローバルプロンプトも不要です。

7. 検証

上記の手順が完了したら：

1. JetBrains IDEを開く

2. codex を起動する

3. HUD経由で起動した場合、HUDが自動的にhook状態を同期する

4. Claude Code公式プラグインをインストールしたJetBrains IDEに戻り、ファイルまたはコードの一部を選択する

5. HUDに現在のファイルと行番号が表示されていることを確認する

6. Codexで通常通り質問する

HUDが更新されない場合、最も確実な方法は以下の通りです：

• IDEに戻り、ファイルを再度クリックする

• または、選択範囲を再度ドラッグし直す

正常な場合：

• ファイルのみを選択すると、Codexはファイルパスのガイドを受け取る

• コード範囲を選択すると、Codexはファイルパスと行番号のガイドを受け取る

• JetBrainsのコンテキストがない場合、JetBrains関連のプロンプトは一切注入されない