Codex JetBrains HUD + Hooks 연동 설명

프로젝트 배경: 이 어댑터 솔루션은 Claude Code v2.1.88 유출 소스 코드 분석을 기반으로 만들어졌으며, Codex가 Claude Code와 유사한 기능을 갖추어 JetBrains 시리즈 IDE에서 현재 선택된 파일, 줄 번호 및 코드 범위를 인식할 수 있도록 하는 것을 목표로 합니다.

Author: nealzhi

본 문서는 단 하나의 연동 경로인 HUD + hooks만 다룹니다.

본 저장소에서는 기존의 "로컬 MCP server + 전역 프롬프트" 방식이 제거되었으며, 더 이상 권장하거나 제공하지 않습니다.

1. 전제 조건

다음 두 가지 조건을 먼저 충족해야 합니다:

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

연동 방식은 두 가지입니다:

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 이전 설정 정리

이전 버전 솔루션을 사용했다면 다음 두 가지를 삭제하세요:

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 server는 중계 계층일 뿐이며, 실제로는 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 server가 없으며 추가적인 전역 프롬프트도 필요하지 않습니다.

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 관련 프롬프트가 전혀 주입되지 않습니다.