# Image Studio
**An image-editing plugin for Codex and Claude Code: fix, sharpen, or create images, change only what you name, and prove the result before calling it done.**
Image Studio has no image model of its own. Your agent's image tool (Codex `image_gen`) and local tools (ImageMagick, an upscaler) make the pixels; Image Studio tells the agent which method to use, checks the result, and remembers your approved work, your taste, and past mistakes across tasks.
| Before (1672×941, wrong pets) | After (repainted, upscaled, repaired) |
| --- | --- |
|  |  |
How this example was made: [tavern hero case](examples/image-repair/tavern-hero-case.md).
## Install
```bash
# Codex
codex plugin marketplace add hbui290/image-studio
codex plugin add image-studio@image-studio
# Claude Code
claude plugin marketplace add hbui290/image-studio
claude plugin install image-studio@image-studio
```
Start a new chat afterwards. To update: `codex plugin marketplace upgrade image-studio && codex plugin add image-studio@image-studio`, or `claude plugin marketplace update image-studio && claude plugin update image-studio@image-studio`. Do not update while a task is running.
Other agents (Cursor, OpenCode, Gemini CLI and others supported by [skills](https://github.com/vercel-labs/skills)): `npx skills add hbui290/image-studio --skill '*'`. Install every skill: the others call scripts in `image-verify`. Or clone this repository and run `python3 scripts/install.py --to <your-skills-directory>` (`--replace` to update; it deletes those skill folders first).
## Use it
Describe the task, or name the skill to be sure (`$image-studio:image-repair ...` in Codex, `/image-studio:image-repair ...` in Claude Code):
| You want to | Skill |
| --- | --- |
| Fix one or more regions (a face, a hand, a removed object, a logo) and keep the rest | `image-repair` |
| Make a new image, banner, or social post | `image-create` (`image-loop` for review-and-repair rounds) |
| Sharpen or upscale, clean cutout edges, logo to SVG, web export | `image-enhance` |
| Check an image before delivery | `image-verify` |
| Find what is wrong, or locate objects | `image-inspect` |
| Plan an edit on a numbered map | `image-edit-map` |
| Extract palette, type, and layout to JSON | `image-reverse-engineer` |
| Rebuild or remix a reference from its parts | `image-reconstruction` |
| Mix several references into directions | `image-inspiration` |
Only the skill that matches is loaded; the others cost a line each.
## How a task runs
1. **Memory:** the agent loads your taste notes, lessons from earlier tasks, and the brand kit (logo, fonts, colors).
2. **Assets and copy first:** it uses your own logo, fonts, and icons, confirms every word and number once, and settles the style (for example 2D, not a 3D render) before the first full image.
3. **Layers:** text, numbers, and logos are never drawn by the generator. `compose_layers.py` places them, and a cut-out subject, on the art, so changing a word or moving the logo takes one run, not a new generation. Text can be laid out inside a box (wrap, shrink to fit, or clip), and a PNG keeps the resolved layout in a tEXt chunk. Styled lettering can be an HTML/CSS layer rendered by headless Chromium (optional Playwright) with page JavaScript and network off.
4. **Hunt:** a fresh `image-hunter` agent checks the whole image once on 100% tiles (AI slop, broken outlines, leftovers, seams, your past complaints). It traces every arm to one hand and counts fingers hand by hand, copies all text word for word, judges each panel of a grid on its own, and checks each reference for traits that leaked in. `mac_vision.py hands` boxes every hand for a close look, and `axis-check` draws a red pommel-to-tip line to prove a sword or staff is straight. `map` draws every problem on one image, so you confirm them all at once.
5. **Repair in one batch:** patches for all confirmed regions are generated in parallel, then:
- `align-check` shows each patch over the base (checker and 50/50 overlay) and refuses a stretched one; `blend` will not paste until those views are accepted with `--accept`;
- `blend` pastes through the mask, matches the patch's color to its surroundings, and reports the color difference (CIEDE2000) and the seam step;
- `edit-check --mask` proves nothing outside the region changed and that the mask took effect; `shape-check` proves a protected object kept its silhouette.
6. **Review rounds** (`image-loop`): an independent `image-reviewer` agent, starting fresh each round, gives one verdict per check. Each round repairs one failure; checks can depend on each other (no judging "the lantern is red" while the lantern is missing); a repair that breaks something that already passed is dropped and retried from the previous image.
7. **Gate:** before the agent may say "done", every problem ever reported must be re-checked on a fresh crop. A hook blocks "done" while the gate has not passed. `crop-check` confirms the focus survives 16:9, 4:5, 1:1, and 9:16 crops and that the image is twice its display size.
## What is inside
| Part | Count | Role |
| --- | --- | --- |
| Skills (`SKILL.md`) | 10 | One workflow each; only the matching one is loaded |
| References | 30 | Detailed rules, opened only when a step needs them |
| Scripts (Python, one Swift helper) | 14 | Measurements the agent runs instead of guessing: `studio_state.py` (memory, gate, defects, `axis-check`, `align-check` with `--auto`, `blend`, `edit-check`, `mask-from-diff`, `shape-check`, `crop-check`), `accel.py` (optional numpy/OpenCV engine), `review.py` and `controller.py` (review rounds), `audit_candidate.py` (pixel audit), `mac_vision.py` (Apple Vision), `compose_layers.py` (text and logo layers) |
| Agents | 2 | `image-hunter` finds problems, `image-reviewer` judges results; neither is the agent that made the image |
| Hooks | 2 | Memory card at session start; block "done" until the gate passes |
Runtime needs only Python with Pillow and jsonschema: no local AI model and no GPU. The measuring commands take one to three seconds on a 4K image. With the optional numpy and OpenCV, the pixel work of `blend` and `edit-check` runs about 5x faster and `align-check --auto` can find a patch's position.
## Speed and tokens
- **One chat per task.** A long chat resends its whole history on every step (one measured chat sent about 227,000 tokens per step). Memory lives in the project store, lessons, and taste notes, so a new chat loses nothing. The session card says when a chat has grown too long.
- **Name the skill** when you know it, so the agent does not guess.
- **Confirm the map once** instead of reporting problems one by one.
- **Images cost the most tokens:** the main chat opens only the map, the thumbnail, and one check view; review tiles (each at most about 1024 px) are opened by the hunter agent.
## Tools
| Needed for | Tool |
| --- | --- |
| Everything that touches pixels | [ImageMagick](https://imagemagick.org/download/) 7 and Python 3.9+ with [Pillow](https://pypi.org/project/pillow/) (run scripts with [uv](https://docs.astral.sh/uv/): `uv run --with pillow --with jsonschema python3 ...`) |
| Generating or redrawing | Codex `image_gen` (Claude Code has no built-in generator; it hands back the prompt) |
| Sharpen or upscale | [Upscayl](https://github.com/upscayl/upscayl) (`upscayl-bin` and models) or [Real-ESRGAN-ncnn-vulkan](https://github.com/xinntao/Real-ESRGAN-ncnn-vulkan) |
| Cutouts, text checks, and hand boxes on macOS 14+ | Built in: `mac_vision.py` uses Apple Vision (no download; needs the Xcode command line tools for `swiftc`) |
| Faster checks and `align-check --auto` (optional) | [numpy](https://numpy.org/install/) and [OpenCV](https://pypi.org/project/opencv-python-headless/) (`opencv-python-headless`): `uv run --with pillow --with jsonschema --with numpy==2.0.2 --with opencv-python-headless==4.11.0.86 python3 ...`; every check also runs on Pillow alone with the same verdict (`--engine pillow`) |
| HTML/CSS text layers in `compose_layers.py` (optional) | [Playwright](https://playwright.dev/python/) and its Chromium, once: `uv run --with playwright==1.48.0 python3 -m playwright install chromium`; then `uv run --with pillow --with jsonschema --with playwright==1.48.0 python3 ...`. Layouts without html layers do not need it |
| Optional | [rembg](https://github.com/danielgatis/rembg) (backgrounds off macOS or when edges matter: `birefnet-general-lite`), [Potrace](https://potrace.sourceforge.net) (logo to SVG), [jsonschema](https://pypi.org/project/jsonschema/) (spec checks and `image-loop`), [Codex CLI](https://github.com/openai/codex) (automated review) |
Model choice by image type, measured results, and licence notes: [enhancement recipes](plugins/image-studio/skills/image-enhance/references/recipes.md). Setup checklist: [tool readiness](plugins/image-studio/skills/image-repair/references/tool-readiness.md).
## Memory and the gate
`studio_state.py init --project PATH --brand ID` creates a `.image-studio/` folder in the project. It keeps approved files (by hash), every reported problem with a stable ID (`D1`, `D2`, ...), and decisions. Lessons and taste notes are shared by every task in `~/.image-studio/` (or `$IMAGE_STUDIO_HOME`).
Two hooks run in Codex (trust them once) and Claude Code: **SessionStart** prints a short memory card when the folder has a store, and **Stop** blocks a "done" or "xong" message while a deliverable has not passed the gate. Both stay silent without a store. Details: [project memory](plugins/image-studio/skills/image-verify/references/project-memory.md); how pass, fail, and stop are decided: [decisions](plugins/image-studio/skills/image-verify/references/decisions.md).
## Limits
- AI reviewers still miss subtle problems (overall softness, uneven outlines). The hunt is a first pass; you make the final call, and what it missed becomes a lesson.
- Upscalers sharpen detail that exists; they cannot recover a face or letter the source never had, and they garble small text.
- A flat image does not reveal its prompt, fonts, or layers.
- Pixel audits refuse 16-bit-per-channel color files (compare 8-bit copies).
- "Passed" means the stated checks passed, not that you approved it.
## Troubleshooting
- **Skills missing or doubled:** start a new chat; remove older copies installed another way (or an old `image-processing` skill).
- **`stop_provider` from `review.py`:** the Codex reviewer could not run (not signed in, no vision model, or over `--timeout`). Use the `image-reviewer` agent or `--report` instead.
- **No upscaler found:** `image-enhance` stops instead of faking it with a sharpen filter; install one from the Tools table.
## Development
```bash
uv run --with pillow --with jsonschema python3 -m unittest discover -s tests
```
Offline tests: no model calls; tests skip themselves when a dependency is missing. Changes are listed in [CHANGELOG](CHANGELOG.md).
To measure the hunt on real images, label the known problems of each test image and score the hunter's table with `bench/score.py` (recall per kind of problem, and precision): see [bench](bench/README.md).
MIT license. See [NOTICE](NOTICE) for sources and [third-party notices](plugins/image-studio/THIRD_PARTY_NOTICES.md) for adapted MIT code.