<!-- Source: https://github.com/wjb127/codex-image Author: wjb127 (Copyright (c) 2026 wjb127) License: MIT — see ./LICENSE Based on: upstream commit 91011992ebb0d199124240af734736e8253ee37e (2026-04-23) Notes: Modified from upstream by basejb. -->

codex-image — AI Image Generation via Codex OAuth

Generate images using OpenAI's gpt-image-2 model through Codex CLI. No API key required — uses Codex OAuth (ChatGPT login) authentication.

OpenAI Codex CLI의 내장 image_gen 도구를 통해 gpt-image-2 모델로 이미지를 생성한다. API 키 불필요 — Codex OAuth(ChatGPT 로그인) 인증 사용.

How it works / 동작 원리

User prompt → Claude Code (/codex-image)
  → codex exec (OAuth token auto-managed)
    → built-in image_gen tool (gpt-image-2)
      → ~/.codex/generated_images/<session>/
        → copy to project root

Important: OAuth tokens cannot call OpenAI REST API directly (returns 401). Must go through codex exec which handles auth internally.

>

OAuth 토큰으로 OpenAI REST API 직접 호출 불가 (401 반환). 반드시 codex exec 경유 — Codex가 내부적으로 인증 처리.

Step 1 — Verify Codex CLI & Auth / Codex CLI 및 인증 확인

which codex 2>/dev/null && codex --version 2>/dev/null || echo "NOT_FOUND"

If NOT_FOUND, stop:

"Codex CLI not installed. Run npm install -g @openai/codex then codex login." "Codex CLI 없음. npm install -g @openai/codex 후 codex login 실행해."

codex login status 2>&1

If not "Logged in":

"Codex login required. Run codex login in terminal. OAuth login enables image generation without API key." "Codex 로그인 필요. 터미널에서 codex login 실행. OAuth 로그인하면 API 키 없이 이미지 생성 가능."

Step 2 — Parse Arguments / 인자 파싱

Extract from $ARGUMENTS:

Parsing note for `--reference`: The flag may appear zero or more times. Initialize an empty array before parsing: _REFERENCES=(). Append each value with _REFERENCES+=("$value"). Path validation and error handling happen in Step 4's bash block — do not re-validate here.

Remaining text → image prompt / 나머지 텍스트 → 이미지 프롬프트

If prompt is empty, ask via AskUserQuestion:

"What image should I generate? Enter a prompt." "어떤 이미지를 생성할까? 프롬프트를 입력해줘."

Step 3 — Determine Save Path / 저장 경로 결정

_PROJECT_ROOT=$(git rev-parse --show-toplevel 2>/dev/null || pwd)
_OUT_DIR="${_PROJECT_ROOT}"
_TIMESTAMP=$(date +%Y%m%d-%H%M%S)
_FILENAME="codex-image-${_TIMESTAMP}"

• If --out specified, use that path / --out 지정 시 해당 경로 사용
• Single image: codex-image-<timestamp>.png
• Multiple (-n > 1): codex-image-<timestamp>-1.png, -2.png, ...
• Never overwrite existing files / 기존 파일 덮어쓰기 금지

Step 4 — Generate Image / 이미지 생성

# Build -i argument array for references (zero or more).
# Array form avoids eval, so paths containing spaces, backticks, or $(...) are
# passed as literal file paths — no shell re-parsing, no injection surface.
_REF_ARGS=()
for ref in "${_REFERENCES[@]}"; do
  if [ ! -f "$ref" ]; then
    echo "ERROR: Reference image not found: $ref" >&2
    exit 1
  fi
  _REF_ARGS+=(-i "$ref")
done

# Include reference hint in the prompt if any references are attached
_REFERENCE_HINT=""
if [ "${#_REF_ARGS[@]}" -gt 0 ]; then
  _REFERENCE_HINT=" Use the attached image(s) as strong style references for tone, color palette, typography, and layout."
fi

_BACKGROUND_LINE=""
if [ -n "${_BACKGROUND}" ] && [ "${_BACKGROUND}" != "auto" ]; then
  _BACKGROUND_LINE="
6. Background: ${_BACKGROUND} — pass background='${_BACKGROUND}' as a parameter to the image_gen tool. When transparent, the saved PNG MUST include an alpha channel (RGBA, color type 6); do not flatten onto white. Verify after generation that the corners of the output are transparent before reporting success."
fi

_CODEX_PROMPT="Perform the following tasks:
1. Use the built-in image_gen tool to generate an image.${_REFERENCE_HINT}
2. Prompt: ${_PROMPT}
3. Size: ${_SIZE}
4. Quality: ${_QUALITY}
5. Count: ${_N}${_BACKGROUND_LINE}
7. Copy the generated image to '${_OUT_DIR}/${_FILENAME}.png'. For multiple images use -1.png, -2.png suffix.
8. Print the saved file path and size."

if [ "${#_REF_ARGS[@]}" -gt 0 ]; then
  # With references: -i flags on command line, prompt on stdin.
  # `codex exec -i <FILE>...` is variadic and would swallow a trailing prompt
  # positional arg as another file path, so the prompt must go to stdin.
  codex exec "${_REF_ARGS[@]}" \
    -C "${_PROJECT_ROOT}" \
    -s workspace-write \
    -c 'model_reasoning_effort="medium"' \
    --skip-git-repo-check \
    <<<"${_CODEX_PROMPT}" 2>&1
else
  # Without references: existing behavior — prompt as positional argument.
  codex exec "${_CODEX_PROMPT}" \
    -C "${_PROJECT_ROOT}" \
    -s workspace-write \
    -c 'model_reasoning_effort="medium"' \
    --skip-git-repo-check \
    2>&1
fi

timeout: 120000ms (2 min)

Required flags / 필수 플래그

• -s workspace-write — file write permission / 파일 쓰기 권한
• --skip-git-repo-check — works outside git repos / git 레포 외부에서도 실행 가능

Internal flow (Codex side) / 내부 동작 흐름

1. Codex calls built-in image_gen tool (gpt-image-2)
2. Image saved to ~/.codex/generated_images/<session-id>/ig_*.png
3. Codex copies file to specified project path
4. Reports file path and size

Step 5 — Display Result / 결과 출력

═══════════════════════════════════════════════
IMAGE GENERATED / 이미지 생성 완료
═══════════════════════════════════════════════
Prompt: <prompt used>
Size: <size>
Quality: <quality>
Count: <n>
Auth: OAuth (ChatGPT)
───────────────────────────────────────────────
<saved file path(s)>
═══════════════════════════════════════════════

Always display the generated image using the Read tool. 생성된 이미지를 반드시 Read 도구로 표시한다.

Step 6 — Follow-up / 후속 안내

• "Run /codex-image again to generate another image."
• For Next.js projects: suggest moving to public/images/ if needed.

Error Handling / 에러 처리

Rules / 규칙

• Always use the Read tool to display generated images / 생성된 이미지는 반드시 Read로 표시
• Never overwrite existing files — always use timestamped filenames / 기존 파일 덮어쓰기 금지
• OAuth only — do not attempt direct REST API calls with OAuth token (returns 401) / OAuth 토큰으로 REST API 직접 호출 금지
• Verify prompt intent before generating / 생성 전 프롬프트 의도 확인