CI Python 3.11+ License: MIT

A polished, Python-first wrapper for local Codex CLI image generation that is designed for Hermes/OpenClaw skills, reproducible local automation, and honest public documentation.

What you get: a small CLI + reusable skill script that checks local Codex login, runs codex exec, finds the generated image, copies it to a stable output path, and emits machine-readable JSON.

• First-time AI users who want copy-paste install steps
• Hermes/OpenClaw users who want to reuse a local Codex login for image generation
• Agents/automation workflows that need predictable output files and JSON metadata

If you want the shortest safe path, run this first:

git clone https://github.com/techkwon/hermes-codex-image-skill.git
cd hermes-codex-image-skill
python3.11 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip setuptools wheel
pip install -e .[dev]
hermes-codex-image --help

If hermes-codex-image --help prints usage text, the install worked.

After a healthy install, hermes-codex-image --help should look roughly like this:

usage: hermes-codex-image [-h] [-o OUTPUT_PATH] [--timeout TIMEOUT]
 [--metadata-json METADATA_PATH]
 [--extra-arg EXTRA_ARGS] [--version]
 prompt
Generate an image through local Codex CLI and emit structured JSON.

After a healthy repo verification, make doctor should end with a successful build summary.

If something fails, check these 5 first:

1. python3.11 --version
2. codex --version
3. codex login status
4. hermes-codex-image --help
5. make doctor

Quick guide: docs/TROUBLESHOOTING_QUICK.md Beginner FAQ: docs/FAQ.md Preview copy: docs/GITHUB_PREVIEW_COPY.md Instagram promo pack: docs/INSTAGRAM_PROMO_PACK.md

Beginner quick route

1. Read docs/HERMES_AGENT_INSTALL.md
2. If you prefer Korean, also read docs/README.ko.md
3. If you want the visual route, open docs/VISUAL_QUICKSTART.md
4. Run the install commands exactly as written

If you are handing this repo to Hermes/OpenClaw

1. Tell the agent to read AGENTS.md
2. Ask it to check Python, Codex install, and Codex login first
3. Then ask it to install the repo and verify ruff, pytest, and python -m build

Open this repository and install it for me like I am a first-time user. Check Python first, check whether Codex is installed and logged in, create the virtualenv, install the package, run lint/tests/build, and then summarize exactly what worked and what still needs my action.

이 저장소를 초심자 기준으로 설치해줘. Python 먼저 확인하고, Codex 설치 여부와 로그인 상태를 확인한 다음, 가상환경을 만들고, 패키지를 설치하고, lint/test/build까지 검증한 뒤 무엇이 성공했고 무엇이 내 수동 조치가 필요한지 정확히 알려줘.

Local Codex image generation is useful in practice, but the raw workflow is awkward for automation:

• output paths are buried in Codex stdout or under ~/.codex/generated_images/...
• higher-level automations need structured JSON, not ad-hoc terminal scraping
• team workflows need explicit limitations and reproducible examples

This repository packages that path into something you can actually reuse.

Paper Banana hero

Banana card

• Codex preflight checks
  • verifies codex exists in PATH
  • verifies local login state with codex login status
• Stable image discovery
  • extracts image paths directly from stdout when available
  • falls back to scanning ~/.codex/generated_images or $CODEX_HOME/generated_images
• Automation-friendly output
  • returns structured JSON
  • optionally writes the same metadata to a sidecar JSON file
• Hermes/OpenClaw ready
  • includes a skill/ folder with a reusable script entrypoint
• Public-quality safety rails
  • explicit limitation docs
  • tests for parsing, fallback discovery, preflight failures, and timeout handling

This repository is intentionally narrow.

It is not:

• a replacement for the OpenAI Images API
• proof of the exact backend image model identity used by Codex
• a full GUI or proxy service
• guaranteed to survive future Codex CLI behavior changes without maintenance

If you need a hosted API or direct model selection guarantees, use the official image API path instead.

We found related public work already exists.

• Akuma-real/codex-canvas — Textual/TUI workflow around Codex image generation
• starhunt/duct-cli — OpenAI-compatible adapter/proxy around Codex image generation
• aymenbouferroum/gpt-imagen — Claude Code plugin workflows for GPT Image-style generation/editing

This project focuses on:

• Hermes/OpenClaw skill packaging
• Python implementation that is easy to inspect and extend
• local Codex login reuse instead of API-only orchestration
• clear public documentation of limits and assumptions

More detail: docs/COMPARISON.md

If you are completely new, start with docs/HERMES_AGENT_INSTALL.md. If you prefer Korean, also read docs/README.ko.md. Those guides are written for both human beginners and Hermes/OpenClaw agents.

git clone https://github.com/techkwon/hermes-codex-image-skill.git
cd hermes-codex-image-skill
python3.11 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip setuptools wheel
pip install -e .[dev]

make PYTHON=python3.11 install

If your Python 3.11+ interpreter has a different name, point PYTHON at it explicitly.

• Python 3.11+
• local codex CLI available in PATH
• successful local codex login

Quick health checks:

codex --version
codex login status

hermes-codex-image \
 "Generate a premium hero image for a research visualization product called Paper Banana. Add Korean headline text exactly as: 논문을 한눈에" \
 --output /tmp/paper-banana-hero.png \
 --metadata-json /tmp/paper-banana-hero.json

Example JSON:

{
 "ok": true,
 "source_path": "/Users/name/.codex/generated_images/.../ig_xxx.png",
 "final_path": "/tmp/paper-banana-hero.png",
 "mode": "copied",
 "session_id": "019d...",
 "login_status": "Logged in using ChatGPT",
 "model_hint": "gpt-5.4",
 "started_at": "2026年04月23日T14:18:05.846883+00:00",
 "finished_at": "2026年04月23日T14:19:57.076225+00:00",
 "duration_seconds": 111.231,
 "error": null
}

hermes-codex-image --help

The repository includes a reusable skill entrypoint under skill/.

For an agent-friendly handoff, see:

• AGENTS.md
• docs/HERMES_AGENT_INSTALL.md

Packaging note: the installable Python package focuses on the CLI/runtime code. Repository resources such as skill/, docs/, and example assets are intended for GitHub/source-distribution use.

python3 skill/scripts/generate_with_codex.py \
 "Generate a soft pastel onboarding illustration for an AI research workspace" \
 --output /tmp/onboarding.png \
 --metadata-json /tmp/onboarding.json

The script bootstraps src/ into sys.path, so it works from a fresh clone before packaging.

flowchart LR
 A[User prompt] --> B[hermes-codex-image CLI]
 B --> C[Check codex binary]
 C --> D[Check codex login status]
 D --> E[Run codex exec]
 E --> F{Image path in stdout?}
 F -- Yes --> G[Use stdout path]
 F -- No --> H[Scan generated_images directory]
 G --> I[Copy to stable output path]
 H --> I
 I --> J[Return JSON and optional metadata sidecar]

See docs/EXAMPLES.md for more, including Korean examples.

hermes-codex-image \
 "Generate a premium hero image for a research visualization product called Paper Banana. Show a realistic peeled banana transforming into layered academic charts on a clean desk. Add Korean headline text exactly as: 논문을 한눈에" \
 --output /tmp/paper-banana-hero.png

hermes-codex-image \
 "Generate a premium flat illustration of a single yellow banana centered on a very light cream background card with soft shadow. Clean modern product-asset style. No text." \
 --output /tmp/banana-card.png

make lint
make test
make build

Equivalent manual commands:

source .venv/bin/activate
ruff check .
pytest
python -m build

GitHub Actions runs:

• Ruff
• pytest
• build verification
• Python 3.11 / 3.12 matrix

• Comparison with similar projects
• Known limitations
• Example prompts
• Architecture notes
• Release checklist
• Contributing guide

Before sharing outputs produced by this tool:

1. visually inspect the generated image
2. keep prompts and outputs under version control when relevant
3. avoid claiming an exact backend image model unless verified separately
4. document that the workflow depends on local Codex behavior

• richer error classification for more Codex failure modes
• stronger regression fixtures for stdout/output-directory variations
• optional prompt preset library for Korean and English workflows
• pipx-friendly distribution polish

MIT