Skip to main content
skill CX Codex

edit-image — Claude Code skill: what it does, how to install

edit-image modifies existing picture files with OpenAI gpt-image-2 via Codex CLI, altering isolated details, applying brand colors, or generating matching variants.

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 edit-image does

This tool forwards source assets to the codex-imagegen wrapper using --ref flags. The model keeps unmentioned elements unchanged and writes the output to a fresh file path. You can pass up to 4 reference images to split subject and style targets within the prompt.

Execution requires a Bash timeout of 300000 ms or higher. When transparent backgrounds are needed, the tool places the subject on a #00FF00 canvas and strips it using the bundled remove_chroma_key.py script. Native alpha channels require an OPENAI_API_KEY.

Every edit consumes ChatGPT plan quota. Standard pixel operations like rotating, resizing, or cropping are best handled directly by ImageMagick or sips without model inference.

What it helps with

  • swap backgrounds while preserving the primary subject
  • recolor interface icons to match hex brand palettes
  • create new sibling assets aligned with reference design styles
  • update labels and text on existing artwork

Example prompts for the agent

  • Change the sky to sunset orange in ./assets/hero.png and save to ./out/hero-sunset.png, keep people identical
  • Recolor ./assets/icon.png to #2563EB on white while keeping exact shapes
  • Make a settings gear icon matching the stroke and palette of ./assets/home.png

How to install edit-image

1Plugin marketplace

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

This installs the whole codex-bridge plugin with all its skills

2Manually: put the files in place

~/.claude/skills/edit-image/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/edit-image/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about edit-image

How to install edit-image in Claude Code?

Register the marketplace and install the package with /plugin marketplace add Sateezg/codex-bridge, followed by /plugin install codex-bridge@codex-bridge.

What does edit-image do?

It applies targeted changes to graphics via OpenAI gpt-image-2 using the Codex CLI, preserving unmentioned areas and outputting to a new path.

Can edit-image overwrite the original image?

The source file is never modified. The CLI wrapper always saves results into a separate destination and prints that path.

Source text

SKILL.md · MIT
---
description: Edit, restyle, or vary an EXISTING image file using OpenAI gpt-image-2 through the Codex CLI — change one thing and keep the rest, swap a background, recolor to a brand palette, add or fix text, or produce style-matched variants of a reference image. Use whenever the user points at an image file and asks to change, fix, restyle, clean up, or make a version of it.
---

# Edit an existing image (gpt-image-2 via Codex CLI)

Same wrapper as generation, plus `--ref` to attach the source image:

```bash
codex-imagegen "<what to change>" <output.png> --ref <source.png> [--size WxH]
```

The wrapper attaches the reference with `codex exec -i`, tells Codex to preserve
everything not mentioned, and prints the absolute path of the new file. **The
source file is never modified** — always write to a new path.

## Examples

```bash
# change one thing, keep the rest
codex-imagegen "change the sky to a sunset orange, keep the building and people identical" \
  ./out/hero-sunset.png --ref ./assets/hero.png

# recolor to a brand palette
codex-imagegen "recolor to a monochrome palette of #2563EB on white, keep the exact shapes" \
  ./out/icon-blue.png --ref ./assets/icon.png

# style-matched sibling asset
codex-imagegen "a settings gear icon in exactly the style of the reference: same stroke weight, same palette, same corner radius" \
  ./out/settings.png --ref ./assets/home.png
```

Up to four `--ref` images can be passed — useful when one is the subject and the
others are style references. Say in the prompt which is which.

## Writing the change description

Be surgical. The model preserves what you don't mention, so name the change and
then name what must survive it:

- Good: *"replace the text on the sign with 'OPEN 24/7', keep the font style, lighting and every other element identical"*
- Bad: *"make it better"* — produces an unrelated image

For a series of edits, chain them one at a time (each output becomes the next
`--ref`) rather than stacking five changes into one prompt.

## Rules

1. **Never overwrite the source.** Write to a new file; offer to replace only after
   the user has seen the result. Note that Codex itself resists overwriting — the
   wrapper prints the path actually written, which may be a versioned sibling like
   `out-v2.png`. Use the printed path, not the one you asked for.
2. **Verify by viewing.** Read the output PNG with the Read tool and compare
   against the request before reporting done. Regenerate with a sharper prompt if
   the model drifted — at most 2 retries.
3. **Use a Bash timeout of at least 300000 ms** (5 minutes).
4. **For a transparent result**, regenerate the subject on a flat `#00FF00`
   background (`#FF00FF` if the subject is green) and strip the key with the
   helper Codex ships:
   ```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
   ```
   Verify transparent corners and no colour fringe afterwards. True native
   transparency needs Codex's CLI fallback plus an `OPENAI_API_KEY` — only raise
   that option for hard subjects (hair, fur, glass, smoke) and let the user decide.
5. **Not for precise pixel work.** Cropping, resizing, rotating, format conversion
   and compression are faster and lossless with ImageMagick or `sips` — use those
   directly instead of regenerating.
6. Each edit spends the user's ChatGPT plan quota. Don't loop unprompted.

For multi-image jobs, hand the whole brief to the `codex-artist` subagent instead.

© Sateezg · MIT · Sateezg/codex-bridge

Similar skills

All skills for Design →

From the same set12

The whole set →
ask-codex ask-codex is a Claude Code skill that sends a question about the current repo to OpenAI Codex (GPT-5) and returns the answer without a subagent. For one-off questions, a second opinion, and bug searches. CX Codex +1 ★ 195repo stars codex-reviewer codex-reviewer is a Claude Code subagent that independently reviews diffs with OpenAI Codex and verifies each finding against the actual files. CX Codex ★ 195repo stars 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 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 codex-artist 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. 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

Project sponsors

Companies that keep this analytics open