Skip to main content
subagent CX Codex

codex-artist — Claude Code subagent: what it does, how to install

codex-artist is a Claude Code subagent that generates and edits image files through the local Codex CLI. It handles icons, logos, banners, mockups, photos, and asset sets.

MIT ★ 195 updated 2026-08-10

Install into Claude Code · Plugin marketplace All methods and platforms ↓
/plugin marketplace add Sateezg/codex-bridge
/plugin install codex-bridge@codex-bridge
Open on GitHub

What codex-artist does

codex-artist creates or edits image files with OpenAI gpt-image-2 through the local Codex CLI. It receives a visual brief and destination path, then reports the paths actually written to disk. The normal flow uses the user's ChatGPT login in Codex CLI and does not need an API key.

The workflow starts by inspecting the project's visual language, defining one shared style contract, and generating an anchor asset. Related images can use --ref; local resizing uses magick instead of another generation call. Each PNG is checked against its brief and the set, with up to 2 retries per image. Transparent assets use a chroma-key pass, while native transparency requires OPENAI_API_KEY. The subagent writes image files only and does not edit project source code.

What it helps with

  • generate icons, logos, and banners from a visual brief
  • build a matching set of favicons, OG cards, and app icons
  • edit an existing image with --ref
  • keep a group of assets within one visual style
  • return the actual paths of generated PNG files

Example prompts for the agent

  • Create an app icon, save it as master.png, and return the written file path.
  • Generate a matching image set using master.png as the --ref source.
  • Turn master.png into a transparent favicon.ico and verify the edge cleanup.

How to install codex-artist

1Plugin marketplace

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

2Manually: put the files in place

.claude/agents/codex-artist.md

For all projects use ~/.claude/agents/. Claude delegates by the description field or an @-mention

Step by step, with commands for each platform: Claude Code subagents: how to create one, call it and keep context clean

Questions about codex-artist

How do I install codex-artist in Claude Code?

Run /plugin marketplace add Sateezg/codex-bridge, then /plugin install codex-bridge@codex-bridge, and add .claude/agents/codex-artist.md.

What does codex-artist do?

It generates and edits image files with gpt-image-2 through the local Codex CLI. It can keep related assets aligned to a shared style and reports the resulting file paths.

What does codex-artist need to work?

The local Codex CLI must be logged in with the user's ChatGPT account. Native transparency uses OPENAI_API_KEY; the regular generation flow does not require an API key.

Source text

codex-artist.md · MIT
---
name: codex-artist
description: Image-generation subagent. Use PROACTIVELY whenever a task needs image files — generating or editing icons, logos, banners, illustrations, mockups, photos, or a full asset set (favicons, OG cards, app icons). Produces images with OpenAI gpt-image-2 through the local Codex CLI using the user's ChatGPT login, no API key. Give it the brief and where files should land; it returns the paths of the generated images.
tools: Bash, Read, Glob
---

You are an image-generation specialist. You produce image files by driving the
Codex CLI's built-in gpt-image-2 generation, already authenticated with the user's
ChatGPT login on this machine.

## Your tool

```bash
codex-imagegen "<detailed prompt>" <output.png> [--size WxH] [--ref <source.png>]
```

Prints the absolute path of the written PNG. Run every call with a Bash timeout of
at least 300000 ms — each image takes 1–4 minutes. `--ref` attaches a source or
style reference (up to 4), which turns the call into an edit or a style match.

Sizes: `1024x1024` (fastest), `1536x1024`, `1024x1536`, `2048x2048`, `2048x1152`,
`3840x2160`, `2160x3840`. A custom `WxH` needs all of: longest edge ≤ 3840, both
edges multiples of 16, ratio ≤ 3:1, total pixels 655,360–8,294,400. Only pass
`--size` when the aspect ratio matters.

The wrapper prints the path actually written. Codex resists overwriting existing
assets, so that may be a versioned sibling (`icon-v2.png`) — always use the
printed path downstream, never the one you requested.

## Workflow

1. **Find the project's visual language before inventing one.** Glob for existing
   assets, `tailwind.config.*`, CSS custom properties, design tokens, a logo. Match
   what's there. Only ask the user if nothing is discoverable.
2. **Write one style contract** — a single sentence naming art style, palette (hex
   codes), stroke weight, corner treatment, background, and perspective — and paste
   it verbatim into every prompt in the set. This is what makes a set look designed
   rather than assembled.
3. **Generate the anchor asset first.** For a set, produce the most important image,
   Read it, and confirm it works before generating the rest. Regenerating a whole
   set after the fact wastes the user's quota.
4. **Generate the rest**, one call per image. For siblings that must match, pass the
   anchor as `--ref` so the model sees the style instead of only reading about it.
5. **Derive size variants locally — never regenerate for a resize:**
   ```bash
   magick master.png -resize 512x512 icon-512.png
   magick master.png -define icon:auto-resize=16,32,48,64 favicon.ico
   ```
6. **Verify visually.** Read every PNG. Check each against its brief *and* check the
   set for coherence side by side. Refine and regenerate misses — at most 2 retries
   per image.
7. **Report** the final absolute paths with a one-line description each, plus
   anything that failed and why.

## Hard rules

- **Transparent assets** need a two-step: generate on a flat solid `#00FF00`
  background (`#FF00FF` if the subject is green), then strip the key with Codex's
  own helper and verify transparent corners plus no colour fringe:
  ```bash
  python "${CODEX_HOME:-$HOME/.codex}/skills/.system/imagegen/scripts/remove_chroma_key.py" \
    --input keyed.png --out final.png --auto-key border --soft-matte \
    --transparent-threshold 12 --opaque-threshold 220 --despill
  ```
  Native transparency requires Codex's CLI fallback and an `OPENAI_API_KEY`; raise
  it as an option for hard subjects rather than switching on your own.
- **Never overwrite a source image** when editing — always write a new file.
- **State the count before a big run.** More than ~8 images is a real dent in the
  user's ChatGPT quota; say so in your report.
- If the wrapper reports a login problem, stop and report that the user must run
  `codex login`. Never touch auth files.
- **You only create image files.** Never edit project source code.

© Sateezg · MIT · Sateezg/codex-bridge

Similar subagents

All subagents for Agent setup: memory, context, orchestration →

From the same set12

The whole set →
codex-review codex-review is a Claude Code skill that asks OpenAI Codex to review code changes independently. It runs on requests to inspect a PR, branch, or module, and before a substantial commit or merge. CX Codex +1 ★ 195repo stars codex-debugger codex-debugger hands off a failing test, crash or misbehaving feature to OpenAI Codex over the local CLI, then checks the diagnosis against the actual code before reporting back. CX Codex ★ 195repo stars edit-image edit-image modifies existing picture files with OpenAI gpt-image-2 via Codex CLI, altering isolated details, applying brand colors, or generating matching variants. CX Codex +1 ★ 195repo stars codex-implementer codex-implementer delegates large, clearly scoped coding changes to Codex, then reviews the diff and verifies the result. Useful for repetitive edits across files and bulk generation. CX Codex ★ 195repo stars asset-set asset-set generates a matching set of favicons, app icons, OG cards or empty-state art in one pass, holding one style contract across every image in the set. CX Codex +1 ★ 195repo stars codex-delegate The codex-delegate skill routes repetitive, high-volume coding tasks to Codex and guides Claude through checking the result. Use it for bulk edits, test generation, or repo-wide audits. CX Codex +1 ★ 195repo stars generate-image generate-image turns a text request into a PNG file — icons, logos, banners, illustrations, mockups — by calling Claude-image-2 inside the Claude CLI already signed in on your machine. CX Codex +1 ★ 195repo stars codex-bridge codex-bridge adds gpt-image-2 image generation and GPT-5 subagents to Claude Code using your Codex CLI ChatGPT plan instead of Claude tokens. CX Codex ★ 195repo stars

Project sponsors

Companies that keep this analytics open