codex-bridge

이미 가지고 있는 Codex CLI 로그인으로 Claude에게 Code 이미지 생성 기능과 GPT-5 서브 에이전트 팀을 제공합니다.

License: MIT

No API key required

Claude Code는 이미지를 생성할 수 없으며, 모든 작업이 사용자의 Claude 할당량(quota)을 소모합니다. Codex CLI는 gpt-image-2를 사용하여 이미지를 생성하며, 이는 완전히 별도의 예산인 ChatGPT plan에서 실행됩니다. 이 플러그인은 이 둘을 연결해 줍니다.

얻게 되는 두 가지 기능이 있습니다:

1. Claude가 이미지 생성이 가능합니다. 아이콘, 목업(mockup), 히어로 이미지, 전체 파비콘 세트 등 무엇이든 요청할 수 있습니다. Claude가 프롬프트를 작성하고 Codex를 통해 gpt-image-2를 구동한 다음, 결과물을 보고 누락된 부분이 있으면 재정제합니다.

2. Claude가 GPT-5에 위임(delegate)할 수 있습니다. 네 개의 Codex 기반 서브 에이전트가 검토(review), 디버깅(debugging), 대량 구현(bulk implementation), 이미지 작업을 처리합니다. Claude는 오케스트레이터 역할을 유지합니다: 작업 범위를 설정하고, Codex가 볼륨을 담당하며, Claude가 결과를 검증합니다. 무거운 작업은 ChatGPT 할당량을 사용하며, 그 중간 결과물은 절대 Claude 컨텍스트에 들어가지 않습니다.

<a id="why-no-api-key"></a>

OpenAI API 키 불필요. 모든 것이 codex login을 통해 라우팅되므로, API 크레딧 대신 ChatGPT plan에 청구됩니다.

데모 (Demo)

세트 전체에 걸쳐 통일된 스타일 계약(style contract)을 유지합니다. 각 형제 아이콘은 이전 아이콘을 --ref로 전달받아 생성되었기 때문에, 팔레트, 스트로크 무게(stroke weight), 글리프 스케일(glyph scale), 여백이 매번 재설명되고 재해석되는 대신 유지됩니다:

이 저장소의 모든 이미지는 이 플러그인으로 생성되었습니다. — 위의 GIF, 이 아이콘들, 그리고 소셜 미리보기 카드까지도요. 정확한 명령어와 VHS 녹화 스크립트는 assets/README.md에 있으니, 여러분이 전부 재현할 수 있습니다.

목차 (Contents)

• 데모 · 설치 · 빠른 시작 · 내용물
• 기능 1 — 이미지 · 기능 2 — GPT-5 서브 에이전트
• 작동 방식 · 제한 사항 · 문제 해결

설치 (Install)

사전 요구 사항 (Prerequisites)

/plugin marketplace add Sateezg/codex-bridge
/plugin install codex-bridge@codex-bridge

Claude Code가 요청하는 경우 /reload-plugins를 실행하세요.

세션당 한 번, 설치 없이 사용해 보세요:

git clone https://github.com/Sateezg/codex-bridge.git
claude --plugin-dir ./codex-bridge

스킬 디렉토리에서 자동 로드하기:

git clone https://github.com/Sateezg/codex-bridge.git ~/.claude/skills/codex-bridge
chmod +x ~/.claude/skills/codex-bridge/bin/*

다음 세션에서 codex-bridge@skills-dir로 로드됩니다.

빠른 시작 (Quickstart)

설정할 것이 없습니다. 그냥 평이한 언어로 물어보세요:

generate a hero image for the landing page, save it in assets/
make the sky in assets/hero.png sunset orange, keep everything else
set up favicons and an OG card for this project
...

마지막 것이 흥미로운 경우입니다. Claude는 이것이 여러 파일에 걸친 기계적인 작업임을 감지하고 시작하기 전에 분할을 제안합니다:

이 작업은 동일한 변경 사항으로 34개 파일을 건드립니다. 제가 Codex에게 편집 작업을 맡길 수 있습니다 — 이는 여러분의 ChatGPT 할당량을 사용하며 34개의 파일 덤프를 컨텍스트에서 제외해 줍니다 — 그리고 여기서 diff(차이점)를 검토할 수 있습니다. 원할까요?

내용물 (What's inside)

스킬 (Skills) — Claude가 이것들을 자동으로 가져갑니다. /codex-bridge:<name>으로 호출할 수도 있습니다.

기능 1 — 이미지 (images)

codex-imagegen "흰색 배경의 플랫 벡터 로켓 아이콘, #2563EB, 2px 스트로크, 미니멀" ./rocket.png
codex-imagegen "하늘을 일몰 오렌지색으로 변경하고 나머지는 모두 동일하게 유지해줘" ./out.png --ref ./hero.png
codex-imagegen "설정 기어, 참조와 같은 스타일로" ./settings.png --ref ./home.png

래퍼는 실제로 작성된 경로를 출력합니다. Codex는 기존 자산을 덮어쓰지 않도록 지시받았기 때문에 때때로 out-v2.png와 같이 저장하며, 이 래퍼는 이를 감지하고 (그리고 기본 위치인 ~/.codex/generated_images/<session>/) 실제 경로를 보고합니다.

이것이 채팅 창에 프롬프트를 붙여넣는 것보다 나은 점은 다음과 같습니다: 스킬을 통해 Claude가 사용자의 실제 팔레트를 tailwind.config.*나 디자인 토큰에서 가져와서, 전체 세트에 걸쳐 하나의 스타일 계약을 재사용하여 자산들이 일치하도록 하고, 재생성하는 대신 ImageMagick으로 크기 변형을 파생시키며, 작업을 완료했다고 알려주기 전에 PNG 파일을 열어 확인하게 합니다.

기능 2 — GPT-5 서브 에이전트

핵심은 'Claude가 GPT-5를 호출할 수 있다'는 것이 아닙니다. 핵심은 노동의 분배입니다. Claude가 범위를 설정하고 검증하며, Codex가 대량 작업을 처리합니다.

you ──▶ Claude          작업 범위 정의 및 브리프 작성, 결과 검토
             │
             ▼
...

Codex는 별도의 프로세스로 실행되기 때문에, 그 중간 출력물(읽은 40개 파일, 검색 결과, 생성된 보일러플레이트 등)이 절대로 사용자의 Claude 컨텍스트로 들어오지 않습니다. 사용자에게 청구되는 Claude 토큰은 오직 브리프와 검토에 대해서만 발생합니다.

codex-delegate 규칙에 따라 위임 가능한 작업은 다음과 같습니다: 여러 파일에 걸친 기계적 수정, 대량 생성, 광범위한 리포지토리 검색, 모든 이미지 작업, 그리고 자체적으로 완결된 서브태스크. 위임할 수 없는 것은 다음과 같습니다: 아키텍처 호출, 모호한 요구사항, 대화 기록이 필요한 모든 것, 그리고 작은 수정 사항들입니다 — 2줄 수정에 대한 왕복(round-tripping) 비용이 적게 드는 것이 아니라 더 많이 들게 만듭니다.

모든 서브 에이전트는 동일한 계약을 따릅니다: 기본적으로 읽기 전용, 보고하기 전에 검증, 그리고 검증되지 않은 작업에 대해 절대 성공했다고 주장하지 않습니다. 오직 codex-implementer만이 사용자가 동의한 후에만, 그리고 변경 사항이 검토 가능한 diff로 적용될 수 있도록 깨끗한 작업 트리를 가지고 파일에 쓰기 작업을 수행합니다.

쉘에서 직접 실행하는 예시:

codex-run -C . "rate limiting을 소유한 모듈은 무엇인가요? 파일을 이름 지어주세요"
codex-run -C . -r "이제 최소 패치를 보여주세요"          # -r은 세션을 이어갑니다
git diff main...HEAD | codex-run -C . --timeout 1200 -      # diff를 파이프로 전달합니다

작동 방식

두 래퍼(wrapper) 모두 Codex의 비대화형 모드인 codex exec으로 쉘을 실행합니다.

이미지는 출력 디렉토리에 국한된 workspace-write 샌드박스에서 실행됩니다:

codex exec -C <outdir> -s workspace-write --skip-git-repo-check [-i <ref>...] \
  "$imagegen 이미지 생성 도구를 사용하여 ... ./<file>.png 에 저장하세요 ..."

$imagegen은 Codex의 내장 이미지 스킬입니다. 이 스킬은 사용자의 ChatGPT 자격 증명을 사용하여 gpt-image-2를 호출하고, PNG 파일을 작업 디렉터리에 작성합니다. 래퍼(wrapper)는 파일이 정상적으로 저장되었는지 확인하며—Codex가 대신 $CODEX_HOME/generated_images/에 저장한 경우 그곳으로 폴백(fallback)합니다—그리고 Claude가 이미지를 다시 읽을 수 있도록 절대 경로를 출력합니다.

**텍스트 작업 (Text tasks)**은 이벤트 로그를 스크래핑하는 대신 -o 옵션을 사용하여 최종 메시지를 캡처하므로, 서브 에이전트들은 전체 기록(transcript) 대신 깔끔한 답변을 받게 됩니다:

codex exec -C <dir> -s read-only --skip-git-repo-check -o <tmpfile> "<task>" 

둘 다 빠르게, 그리고 명확하게 실패합니다. codex 바이너리가 없거나 세션이 로그아웃된 경우, 지연되는 대신 즉시 종료 코드 1과 함께 조치 가능한 메시지를 출력합니다. 시간 초과는 124를 반환하며, 둘 다 BSD와 GNU의 stat을 처리하고 timeout/gtimeout이 설치되지 않은 경우 우아하게 저하됩니다.

제한 사항 (Limitations)

• 무료가 아닌 할당량(Quota) 기반. 이미지 생성 횟수는 텍스트 작업보다 ChatGPT 플랜 할당량을 약 3~5배 더 빠르게 소모합니다. OPENAI_API_KEY를 설정하면 Codex는 API 결제 방식으로 전환됩니다.
• 투명도는 두 단계가 필요함. 기본 경로는 알파(alpha) 채널을 방출할 수 없기 때문에, 스킬들은 평면적인 #00FF00 키로 이미지를 생성한 후 Codex가 제공하는 remove_chroma_key.py 헬퍼를 사용하여 이를 제거합니다. 진정한 네이티브 투명도를 구현하려면 Codex의 CLI 폴백과 OPENAI_API_KEY가 모두 필요하며, 스킬들은 이것을 조용히 전환하기보다 선택 사항으로 제시합니다.
• 느림. 이미지당 1~4분이 소요되며, 리포지토리 전체를 대상으로 하는 Codex 작업은 10분 이상 걸릴 수 있습니다. 따라서 스킬들은 이에 맞춰 긴 Bash 시간 초과(timeout) 설정을 합니다.
• Codex는 대화 내용을 알지 못함. 모든 프롬프트는 독립적으로 존재해야 합니다. 이것이 바로 서브 에이전트들이 보고하기 전에 검증하는 이유입니다.
• macOS 및 Linux. Windows에서는 테스트되지 않았습니다.

문제 해결 (Troubleshooting)

기여 (Contributing)

이슈(Issues)와 PR(Pull Request) 환영합니다.

claude plugin validate .
bash -n bin/codex-imagegen && bash -n bin/codex-run

크레딧 (Credits)

• openai/codex — Codex CLI와 그 $imagegen 스킬
• Codex CLI image generation write-up

라이선스 (License)

MIT — LICENSE 참조.