TL;DR

이 저장소는 Claude Code 워크플로에서 로컬 Codex CLI와 Codex app server를 연동해 Claude Code 내부에서 바로 코드 리뷰·대항 리뷰·작업 위임·세션 전송을 수행하도록 하는 플러그인이다. 플러그인은 사용자의 기존 `codex` 바이너리와 인증·설정을 재사용하여 별도 계정 이전 없이 동일한 리포지토 컨텍스트에서 작업을 위임하고 백그라운드 작업을 관리한다. 설치는 Claude Code 마켓플레이스에 플러그인을 추가하고 `/codex:setup`으로 상태를 확인하며 Node.js 18.18 이상과 ChatGPT 구독 또는 OpenAI API 키가 필요하다. 리뷰 게이트는 Stop 훅으로 자동 검증을 수행해 문제가 있으면 응답을 차단할 수 있으나 README는 이 기능이 루프와 사용량 위험을 초래할 수 있음을 경고했다.

주요 기능

• 코드 리뷰를 실행한다. `/codex:review` 명령으로 현재 변경사항이나 브랜치를 읽기 전용으로 검토하고 결과를 `/codex:result`로 확인할 수 있다. 백그라운드 실행과 `/codex:status`, `/codex:cancel`로 장시간 작업의 진행과 취소를 관리할 수 있다.
• 설계 검증용 대항 리뷰를 수행한다. `/codex:adversarial-review` 명령은 특정 결정·위험 영역을 집중적으로 질문하고 대안이나 실패 모드를 압박하는 방식으로 동작한다. 이 리뷰는 포커스 텍스트를 받아 설계·트레이드오프 중심의 검증을 지원한다.
• 작업을 Codex에 위임하고 재개한다. `/codex:rescue`로 버그 조사·수정·작업 재개를 요청할 수 있으며 모델과 노력 수준을 플래그로 지정하여 비용과 속도의 균형을 조정할 수 있다. 위임한 작업은 Codex 세션 ID로 이어받아 `codex resume <session-id>`로 Codex에서 계속 작업할 수 있다.
• Claude Code 세션을 Codex로 전송하는 영속적 스레드를 만든다. `/codex:transfer` 명령은 현재 세션을 Codex 외부 에이전트 형식으로 변환해 동일한 컨텍스트를 유지하면서 Codex에서 이어가게 한다. 전송은 로컬 세션 파일 경로를 소스로 삼을 수 있으며 이전 세션을 계속 사용하도록 설계되어 있다.

어떻게 동작하는가

플러그인은 로컬 환경의 global `codex` 바이너리와 Codex app server를 호출하는 래퍼 역할을 하며 동일한 CLI 인증 상태와 설정을 재사용한다. Claude Code의 명령은 플러그인을 통해 Codex에 위임되며 필요한 경우 `codex:codex-rescue` 같은 서브에이전트를 생성해 백그라운드에서 작업을 실행하도록 만든다. 세션 전송은 Codex의 외부-agent 세션 임포터 규칙을 따르며 변환된 대화는 Codex에서 이어서 열람하거나 재개할 수 있는 형식으로 저장된다.

해결 문제

Claude Code 사용자가 별도 환경 전환 없이 Codex의 코드 리뷰·디버깅·작업 위임 기능을 바로 쓰기 어렵다는 문제를 해결한다. 로컬 Codex 설치와 인증을 재활용하므로 별도 계정 이전이나 복잡한 설정 없이 동일한 리포지토 컨텍스트에서 작업을 옮길 수 있다. 또한 긴 작업을 백그라운드로 옮기고 세션을 Codex로 전송해 작업 연속성을 유지할 수 있게 했다.

차별점

• 로컬 Codex 환경을 그대로 재사용한다. 플러그인은 사용자의 existing `codex` 바이너리와 설정 파일을 호출하므로 별도 원격 인증이나 추가 계정 연동이 필요하지 않다. 이로 인해 Claude Code 내에서 Codex를 직접 호출하는 것과 동일한 인증·설정 일관성이 확보된다.
• 세션 전송과 서브에이전트를 통해 작업 연속성을 유지한다. `/codex:transfer`와 외부-agent 세션 임포터를 통해 Claude Code 대화를 Codex 세션으로 변환해 이어서 작업할 수 있으며 `/codex:rescue`는 전용 서브에이전트를 생성해 장기 작업을 처리한다. 이 흐름은 대화형 세션을 끊지 않고 전문 도구로 이관하는 실무적 이점을 제공한다.
• 리뷰 게이트와 Stop 훅으로 자동 검증 경로를 통합할 수 있다. `/codex:setup --enable-review-gate`로 설정하면 Claude의 응답 흐름에 목표지향 Codex 리뷰를 삽입해 문제가 감지되면 멈춤을 적용한다. 다만 README는 이 기능이 사용량과 루프 위험을 동반한다고 명시해 관리 필요성을 드러냈다.

사용 사례

• 출시 전 코드 리뷰 파이프라인에 자동화된 외부 리뷰를 결합할 때 유용하다. 브랜치 비교 또는 현재 변경사항을 대상으로 `/codex:review`를 실행해 읽기 전용 검토를 확보한 뒤 결과를 바탕으로 추가 수정을 진행할 수 있다. 백그라운드 실행을 통해 개발 흐름을 차단하지 않고도 긴 분석을 진행할 수 있다.
• 심각한 버그 조사와 패치 생성을 Codex에 위임할 때 적합하다. `/codex:rescue`로 실패하는 테스트 원인 조사나 최소 패치 적용 등을 요청하면 Codex가 제안한 수정안을 적용하거나 이어서 작업을 진행할 수 있다. 모델과 노력 수준을 지정해 속도·비용·정밀도 트레이드오프를 조절할 수 있다.
• Claude Code에서 시작한 대화형 디버깅을 Codex로 이어가고 싶을 때 사용한다. `/codex:transfer`가 세션을 변환해 Codex에서 동일한 컨텍스트로 작업을 계속할 수 있게 함으로써 대화 이력을 보존한 상태로 심층 분석을 수행할 수 있다. 이 흐름은 긴 조사나 반복적인 수정 시나리오에서 컨텍스트 손실을 줄인다.

시작하기

마켓플레이스에 플러그인을 추가하고 플러그인을 설치한 뒤 `/reload-plugins`로 플러그인 목록을 갱신한 다음 `/codex:setup`으로 Codex 준비 상태를 확인하는 것이 초기 절차이다. 만약 로컬에 Codex가 설치되어 있지 않으면 `/codex:setup`이 npm을 통해 Codex 설치를 제안하거나 사용자가 `npm install -g @openai/codex`로 직접 설치할 수 있다. 설치 후 슬래시 명령으로 `/codex:review` 등 핵심 명령을 바로 실행해 동작을 확인할 수 있다.

요구사항

• ChatGPT 구독 또는 OpenAI API 키가 필요하다. README는 사용이 Codex 사용량 한도에 영향을 준다고 명시해 인증과 과금 연결을 사전에 확인해야 함을 알리고 있다.
• Node.js 18.18 이상이 필요하다. 플러그인과 일부 설치 흐름이 Node/npm 환경을 전제로 하기 때문에 런타임 버전 제약을 충족해야 한다.
• 로컬에 Codex CLI가 없다면 npm을 통해 전역 설치(`npm install -g @openai/codex`) 또는 `/codex:setup`의 설치 제안을 따라야 하며 설치 후 `!codex login`로 인증을 완료해야 한다.