Инструкция по подключению Codex JetBrains HUD + Hooks

Предыстория проекта: это решение по адаптации было создано на основе анализа утечки исходного кода Claude Code v2.1.88. Цель — наделить Codex возможностями, аналогичными Claude Code, чтобы он мог распознавать текущий выбранный файл, номера строк и диапазон кода в IDE семейства JetBrains.

Автор: nealzhi

В этом документе оставлен только один путь подключения: HUD + hooks.

Из этого репозитория удалено старое решение «локальный MCP server + глобальные промпты», оно больше не рекомендуется и не поддерживается.

1. Предварительные требования

Сначала выполните следующие два условия:

1. Вы используете IDE семейства JetBrains Например: 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 считывает это состояние при отправке сообщения

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, но и автоматически синхронизирует состояние, необходимое для хуков. Это единственный рекомендуемый путь, отдельный процесс синхронизации больше не требуется и не предоставляется.

Файл состояния будет записан в:

.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

Способы подключения:

1. Если вы запускаете codex в каталоге этого репозитория Codex напрямую считает .codex/config.toml и .codex/hooks.json из репозитория, вам не нужно указывать дополнительные пути.

2. Если у вас уже есть свой глобальный файл ~/.codex/hooks.json Не перезаписывайте его, просто объедините конфигурацию UserPromptSubmit из репозитория. Если вы хотите скопировать его в ~/.codex/hooks/, скопируйте весь каталог .codex/hooks/, а не только входной файл.

Назначение .codex/config.toml — включение функции хуков, требуемой официально:

[features]
codex_hooks = true

Согласно официальной документации, хуки по умолчанию отключены, их необходимо включить в config.toml или передать codex --enable codex_hooks при запуске. Кроме того, уровень конфигурации Codex считывается из ~/.codex/config.toml и .codex/config.toml внутри репозитория; если проект не помечен как доверенный (trusted), 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"
          }
        ]
      }
    ]
  }
}

Этот хук считывает локальный файл состояния при каждом UserPromptSubmit:

• Если выбран только файл, он внедряет в Codex информацию о том, «какой файл является текущим»

• Если выбран диапазон кода, он внедряет в Codex «текущий файл + номер строки»

• Если контекст JetBrains отсутствует или состояние устарело, ничего не внедряется

Он не внедряет текст кода, а только дает указания по местоположению.

4.3 Очистка старых конфигураций

Если вы ранее использовали старую версию решения, удалите следующее:

1. Удалите локальную конфигурацию MCP

codex mcp remove jetbrains-selection

2. Удалите подобный контент из ваших собственных глобальных промптов

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

Этот шаг обязателен, иначе модель может продолжать пытаться вызвать несуществующий инструмент MCP, следуя старой логике.

4.4 Содержимое, фактически внедряемое хуком

При выборе только файла внедряется нечто подобное:

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

При выборе диапазона строк кода внедряется нечто подобное:

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

Срок действия состояния по умолчанию составляет 20s. Во время работы HUD состояние обновляется каждые 5s; если HUD завершает работу, хук вскоре перестанет внедрять старое состояние. Вы также можете настроить это время с помощью переменной окружения CODEX_JB_HOOK_MAX_AGE_MS.

5. Почему решение с локальным MCP больше не поддерживается

Основные проблемы старого решения:

• Требовалось дополнительное выполнение codex mcp add, что увеличивало затраты на установку и обслуживание

• Модель обычно полагалась на глобальные промпты, принудительно «вызывая MCP один раз за раунд», даже если вопрос не был связан с выбором в JetBrains, что приводило к лишним действиям

• Решение о том, связан ли выбор с вопросом, должно приниматься на основе текущего запроса; помещение этого в глобальные промпты делало поведение слишком механическим

• Локальный MCP server был лишь промежуточным слоем, фактически все равно нужно было подключаться к плагину Claude Code JetBrains; сохранение этого слоя отдельно не дает преимуществ, но увеличивает сложность

• Старые конфигурации трудно полностью очистить, после миграции легко остаются недействительные имена инструментов или старые промпты

После перехода на HUD + hooks преимущества стали более очевидными:

• Локальное состояние считывается только при отправке сообщения, нет лишних вызовов MCP в каждом раунде

• Внедряемый контент содержит только путь к файлу или номер строки, информация чище, модель сама решает, нужно ли читать файл

• Файлы состояния изолированы по корневому каталогу проекта, каждый проект записывает свой .codex/jetbrains-selection-state.json

• HUD обновляет пульс, пока он активен, после остановки HUD старое состояние автоматически аннулируется по истечении времени ожидания

• Путь подключения более единый, пользователю нужно поддерживать только HUD и хуки, не нужно поддерживать конфигурацию MCP

6. Как работает это решение

Цепочка данных выглядит так:

1. Официальный плагин Claude Code для JetBrains предоставляет информацию о локальном подключении и событиях выбора

2. HUD сопоставляет правильное окно проекта JetBrains на основе текущего рабочего каталога

3. После получения изменений выбора HUD записывает путь к файлу, номер строки и время пульса в .codex/jetbrains-selection-state.json текущего проекта

4. Хук UserPromptSubmit считывает это состояние при отправке сообщения

5. Если состояние действительно, он внедряет легкую подсказку «текущий файл» или «текущий файл + номер строки» в Codex

В этой цепочке нет локального MCP server, и не требуются дополнительные глобальные промпты.

7. Проверка

После выполнения вышеуказанных шагов:

1. Откройте IDE JetBrains

2. Запустите codex

3. Если вы использовали обертку HUD для запуска, HUD автоматически синхронизирует состояние хука

4. Вернитесь в IDE JetBrains с установленным официальным плагином Claude Code и выберите файл или фрагмент кода

5. Убедитесь, что HUD отображает текущий файл и номер строки

6. Задайте вопрос в Codex как обычно

Если HUD не обновляется, самый надежный способ:

• Вернитесь в IDE и снова нажмите на файл

• Или перетащите выделение заново

В нормальных условиях:

• При выборе только файла Codex получит указание на путь к файлу

• При выборе диапазона кода Codex получит указание на путь к файлу и номер строки

• При отсутствии контекста JetBrains никакие подсказки JetBrains внедряться не будут