Image Forge

Image Forge

Pixel-precise image editing with three-tier routing: deterministic CLI tools for exact operations, AI models for semantic edits, vision models for analysis.

Routing Decision

Use AI when the edit requires understanding what is in the image. Use ImageMagick when the edit requires knowing exactly what to do to the pixels.

Tier 1: Deterministic (magick, sips, transparent-background)

Use for operations with exact, numeric parameters:

| Task | Tool | Command | |------|------|---------| | Resize to exact dimensions | magick | magick in.jpg -resize 800x600! out.jpg | | Resize fit (preserve aspect) | magick | magick in.jpg -resize 800x600 out.jpg | | Resize fill + crop | magick | magick in.jpg -resize 800x600^ -gravity center -extent 800x600 out.jpg | | Resize shrink only | magick | magick in.jpg -resize '800x600>' out.jpg | | Crop at offset | magick | magick in.jpg -crop 600x400+100+50 +repage out.jpg | | Center crop | magick | magick in.jpg -gravity center -crop 600x400+0+0 +repage out.jpg | | Auto-trim whitespace | magick | magick in.jpg -fuzz 10% -trim +repage out.jpg | | Format convert | magick | magick in.png -quality 85 out.jpg | | Add text | magick | magick in.jpg -fill white -pointsize 36 -annotate +10+50 'Text' out.jpg | | Composite overlay | magick | magick bg.png fg.png -geometry +50+100 -composite out.png | | Watermark | magick | magick photo.jpg wm.png -gravity SouthEast -geometry +10+10 -compose Dissolve -define compose:args=25 -composite out.jpg | | Adjust brightness/contrast | magick | magick in.jpg -brightness-contrast 10x20 out.jpg | | Adjust saturation | magick | magick in.jpg -modulate 100,130,100 out.jpg | | Grayscale | magick | magick in.jpg -colorspace Gray out.jpg | | Sepia | magick | magick in.jpg -sepia-tone 80% out.jpg | | Blur | magick | magick in.jpg -blur 0x3 out.jpg | | Sharpen | magick | magick in.jpg -sharpen 0x1 out.jpg | | Remove background (AI) | transparent-background | See Background Removal section below | | Remove background (simple) | magick | magick in.jpg -fuzz 15% -transparent white -trim +repage out.png | | Strip metadata | magick | magick in.jpg -strip out.jpg | | Set DPI | magick | magick in.jpg -density 300 out.jpg | | Batch resize | batch_ops.py | python3 scripts/batch_ops.py *.jpg --op resize --width 800 --output resized/ | | Montage/contact sheet | magick | magick montage *.jpg -geometry 200x200+5+5 -tile 4x out.jpg | | Quick format convert (macOS) | sips | sips -s format jpeg in.png --out out.jpg | | Quick resize (macOS) | sips | sips -Z 800 in.jpg --out out.jpg |

Tier 2: AI Semantic (nano-banana-pro / Gemini)

Delegate to the nano-banana-pro skill when the edit requires understanding image content:

• Remove a person/object from a photo
• Change sky, weather, time of day
• Apply artistic style transfer
• Inpaint/outpaint regions
• Generate new image from scratch
• Content-aware fill after object removal

Nano Banana regenerates, it does not edit. Every call re-rolls the entire frame, even when the prompt asks to preserve regions verbatim. Expect ~40% of pixels to drift outside the target area — measured empirically, not hypothesized. For surgical regional edits (change the face, keep everything else identical), use the hybrid pattern in references/compositing.md § Surgical Regional Edits: let NB produce a drifted reference, then composite only the target region onto the pristine original with a feathered alpha mask.

Nano Banana also supports only discrete aspect ratios (1:1, 2:3, 3:2, 3:4, 4:3, 4:5, 5:4, 9:16, 16:9, 21:9). For inputs at other ratios (e.g. 3:1 panoramics), see references/recipes.md § Aspect Ratio Padding for the pad-generate-crop recipe.

Tier 3: Vision Analysis (Claude Read tool)

Use the Read tool to inspect images before/after edits:

• Verify an edit succeeded
• Describe image contents
• Check composition and framing
• Identify colors, objects, text in image

Background Removal

Use transparent-background (InSPyReNet model) for AI background removal. It produces clean alpha mattes with smooth anti-aliased edges — far superior to ImageMagick's -transparent/-fuzz approach, which leaves white fringing in concave regions and jagged edges.

When to use each:

| Method | When | Quality | |--------|------|---------| | transparent-background | Any photo/render with complex foreground (hair, translucent edges, concave regions) | Smooth alpha, no fringing | | magick -transparent white -fuzz N% | Simple shapes on pure white, quick-and-dirty | Fast but aliased edges, misses interior white | | magick floodfill | Remove background from corners only, preserve interior white | Only hits connected regions |

Python API (recommended):

from transparent_background import Remover
from PIL import Image

remover = Remover()
img = Image.open("input.jpg").convert("RGB")
out = remover.process(img, type="rgba")
out.save("output.png")

With trim (most common workflow):

python3 -c "
from transparent_background import Remover
from PIL import Image
remover = Remover()
img = Image.open('input.jpg').convert('RGB')
remover.process(img, type='rgba').save('/tmp/nobg.png')
"
magick /tmp/nobg.png -trim +repage output.png

Install: uv pip install --system transparent-background

Performance: ~2-3s per image on Apple Silicon (MPS). First run downloads the InSPyReNet model (~170MB).

Note: rembg is an alternative but has a broken gradio dependency as of May 2026. transparent-background is the more reliable option.

Scripts

All scripts are in ~/.claude/skills/image-forge/scripts/. Run with python3.

image_info.py — Inspect Image Metadata

python3 ~/.claude/skills/image-forge/scripts/image_info.py photo.jpg
python3 ~/.claude/skills/image-forge/scripts/image_info.py photo.jpg --field dimensions
python3 ~/.claude/skills/image-forge/scripts/image_info.py photo.jpg --field width

Returns clean JSON: dimensions, format, color space, depth, alpha, DPI, ICC profile, EXIF.

image_pipeline.py — Declarative Edit Pipeline

Write a JSON spec, get a single chained magick command. No intermediate files.

# Create spec
cat > /tmp/pipeline.json ` | Shrink only if larger |
| `800x600`, `' out.jpg

Critical Reminders

1. Always +repage after -crop — Virtual canvas offset persists without it
2. -modulate order is B,S,H — Brightness, Saturation, Hue (not H,S,L)
3. Settings persist, operators execute immediately — Order matters in magick commands
4. Use rembg for background removal — rembg i input.jpg output.png (add -a for alpha matting)
5. Quote geometry — >, <, ^ are shell metacharacters
6. -alpha off is permanent in IM7 — Use -alpha deactivate/-alpha activate for temporary toggle
7. Inspect before editing — Run image_info.py first to know dimensions, format, alpha state
8. Pipeline for multi-step — Use image_pipeline.py instead of chaining shell commands
9. Nano Banana drifts the whole frame — Never trust NB to leave regions unchanged. For regional edits, use the surgical composite pattern (see compositing.md § Surgical Regional Edits). Verify with magick compare -metric AE -fuzz 5% before after diff.png — low AE means clean, ~40%+ means full regeneration.

References

Detailed references in ~/.claude/skills/image-forge/references/:

• magick-reference.md — Complete ImageMagick 7 command reference (resize, crop, color, text, drawing, batch, identify)
• compositing.md — All compositing operators (Duff-Porter, mathematical, lighting, HSL, special)
• recipes.md — 30+ recipes (borders, shadows, watermarks, social sizing, color effects, sprites, batch patterns)

Dependencies

| Tool | Version | Install | |------|---------|---------| | ImageMagick | 7.1.2-7 (Q16-HDRI) | brew install imagemagick | | rembg | 2.0.72 | uv pip install rembg | | sips | macOS built-in | — | | Pillow | 10.4.0 | uv pip install Pillow |

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: tdimino
• Source: tdimino/claude-code-minoan
• License: MIT
• Homepage: https://www.minoanmystery.org

Install and usage instructions live in the source repository linked above.