Codex에서 forge 사용하기

forge는 Claude Code와 Codex가 같은 skills/와 .forge/ 상태를 사용하도록 구성돼 있다. 작업 규칙을 두 벌로 복제하지 않고, 질문과 서브에이전트 실행처럼 호스트마다 다른 부분만 hosts/ 어댑터로 분리한다.

설치와 호출

저장소에는 Codex 매니페스트인 .codex-plugin/plugin.json이 포함돼 있다. Codex의 로컬 Marketplace에 이 저장소를 추가하고 플러그인을 설치한 다음, 새 작업을 시작해 스킬을 다시 로드한다. 플러그인 훅은 설치만으로 신뢰되지 않으므로 내용을 검토한 뒤 허용해야 한다.

목적	Claude Code	Codex
계획 시작	/forge:fg-ask	$fg-ask
계획 실행	/forge:fg-run	$fg-run
다음 단계 실행	/forge:fg-next	$fg-next
상태 확인	/forge:fg-status	$fg-status
무결성 검사	/forge:fg-doctor	$fg-doctor

자연어 트리거도 동일하다. 예를 들어 “forge로 새 작업 시작”이라고 말하면 fg-ask가 선택될 수 있다.

공유 코어와 어댑터

.claude-plugin/plugin.json ─┐
                            ├─▶ skills/ + scripts/ ─▶ 같은 .forge/ 상태
.codex-plugin/plugin.json ──┘
                                  │
                                  ├─ hosts/claude/
                                  └─ hosts/codex/

• core/HOST.md: 호스트 판별과 capability 선택 규칙
• core/INTERACTION.md: 질문·선택·확인의 공통 계약
• core/EXECUTION.md: 직렬/병렬 실행과 결과 수집의 공통 계약
• hosts/codex/: Codex의 입력 및 collaboration/subagent 실행 방식
• hosts/claude/: Claude Code의 AskUserQuestion 및 Dynamic Workflow 방식

스크립트 경로는 호스트 자신의 변수를 우선한다 — CLAUDE_PLUGIN_ROOT를 먼저 보고 PLUGIN_ROOT로 fallback한다(PLUGIN_ROOT는 다른 도구도 export할 수 있는 일반적인 이름이라, 그쪽이 이기면 무관한 도구가 경로를 가로챌 수 있다). 이 순서로 두 호스트가 동일한 결정론 스크립트를 실행한다. 정규화 형태의 단일 정의는 core/HOST.md다.

현재 지원 범위

기능	Codex 상태	설명
핵심 루프 (fg-ask → fg-run → fg-learn → fg-done)	지원	동일한 상태 전이와 검증·봉인 규칙 사용
상태/도구 (fg-status, fg-doctor, fg-quick, fg-config)	지원	공통 스크립트와 스킬 사용
독립 작업 병렬 실행 (spawn_parallel)	지원	Codex collaboration/subagent 도구가 없으면 직렬 fallback. 관측 미완 — 도구 부재 시 fallback을 전제하므로 Codex 실측 뒤 확정한다
SessionStart 알림 (session_start)	지원	hooks/hooks.json 기본 탐색; 사용자가 훅을 검토하고 신뢰해야 함. 관측 미완 — .codex-plugin/plugin.json은 훅을 선언하지 않으므로 Codex 실측 뒤 확정한다
fg-next all, fg-loop 무인 주행 (prevent_stop)	제한적	Stop 훅의 재진입 동작은 호스트별 차이가 있어 감독 실행 권장
fg-agents 프로젝트 역할 생성 (project_agents)	제한적	현재 생성 포맷이 .claude/agents/ 중심이므로 Codex 전용 materialize는 후속 작업
역할 지정 위임 (spawn_role)	미확인	역할 카드가 .claude/agents/ 포맷이라 Codex 등가물이 없다 — 기본 서브에이전트로 fallback
플러그인 파일 경로 해석 (plugin_root)	지원	Codex에선 PLUGIN_ROOT로 해석. 우선순위와 정규화 형태는 core/HOST.md
선택 메뉴 (structured_choice)	미확인	번호 텍스트 목록으로 fallback — 어느 호스트에서도 정확하다
fg-loop의 budget-tokens 지출 상한	미지원	계량기가 Claude Code의 트랜스크립트 파일을 읽는다. Codex에서는 budget-tokens: none으로 선언하거나 --transcripts DIR로 경로를 지정한다(미지정 시 blocked-health로 정지 — fail-closed)
fg-statusline (status_display)	미지원	Codex에서는 $fg-status 사용
fg-showme 확정-클릭 즉시 반영 (event_wake)	미확인	현재 false — 확정한 뒤 터미널에 아무거나 보내야 재개되며 fg-showme가 세션 시작 시 이를 한 번 밝힌다. 후보 메커니즘은 있다: Codex ≥0.149.0의 codex queue --thread <session_id> --message가 idle 세션을 깨운다(릴리스 노트 "wake idle sessions reliably"). 단 Claude의 Monitor(에이전트가 파일을 pull)와 달리 push형이라 events를 감시해 codex queue를 부르는 watcher와 SessionStart 훅 페이로드의 session_id가 필요하고(훅 자체는 턴을 시작 못 함), fg-showme 안에서의 end-to-end 관측은 Codex 세션에서 해야 한다 — 관측 뒤 true로 확정

이 표는 산문이 아니라 선언이다 — 같은 내용이 hosts/codex/capabilities.json의 9개 키에 기계가 읽는 형태로 들어 있고, 둘은 항상 함께 갱신한다. npm run release:check가 9개 키가 모두 이 표에 이름으로 등장하는지를 강제한다(상태 문구 자체의 타당성은 사람이 검토한다 — 게이트가 하는 일을 넘겨 말하지 않는다). 능력은 그 호스트가 실제로 제공하는 것을 관측했을 때만 true이며, 미확인은 false가 기본값이다 — 모든 능력에는 정의된 fallback(직렬 실행·번호 목록·명시적 정지)이 있어서, 도는 fallback이 없는 도구를 부르는 것보다 항상 싸기 때문이다. false를 true로 바꾸는 것은 가정이 아니라 관측이다(core/HOST.md).

호스트를 바꿔 이어서 작업하기

Forge 상태는 호스트가 아니라 저장소의 .forge/에 저장된다. Claude Code에서 계획을 만든 뒤 Codex에서 $fg-status 또는 $fg-next로 이어가거나, 반대로 Codex에서 실행한 작업을 Claude Code에서 회고·봉인할 수 있다. 단, 두 호스트가 같은 브랜치와 working tree를 보고 있어야 한다.

릴리스 검사

npm run release:check

이 검사는 Claude/Codex 매니페스트 버전, 공통 skills/ 경로, 기본 훅 파일, 양쪽 호스트 어댑터 존재 여부를 함께 확인한다. fg-doctor도 Codex 매니페스트가 존재할 때 네 버전 위치의 drift를 검사한다.