claude-image-generation

Claude Code plugin for generating and editing images using Google Gemini, OpenAI GPT Image, and xAI Grok Image APIs.

Features

• Text-to-image generation with Google Gemini, OpenAI GPT Image 2, or xAI Grok Image
• Image editing with text instructions (all providers)
• Multi-image input — repeatable --input-image for multi-image edits (all providers) and Gemini reference-based generation
• Parallel generation across all providers via scripts/run-all.sh — one shared streaming pane, council-style colored banners, and a pending-provider spinner shown until the first image renders
• Interactive provider selection via AskUserQuestion at runtime
• Inline image preview -- generated images display directly in the terminal (iTerm2, Kitty, Ghostty, WezTerm, Sixel terminals)
• Tmux pane display -- opens a split pane for image preview when running inside tmux (works with Claude Code). Providers running at the same time share one pane, however they were launched
• Streaming display -- images appear progressively in a shared pane during parallel generation, accumulating as each provider finishes
• Open in Finder/Preview -- press 'f' for Finder or 'p' for Preview in the display pane

Installation

From marketplace (recommended)

# Add the hex-plugins marketplace (once)
/plugin marketplace add hex/claude-marketplace

# Install the plugin
/plugin install claude-image-generation

From GitHub

/plugin install hex/claude-image-generation

Manual

git clone https://github.com/hex/claude-image-generation.git
claude --plugin-dir /path/to/claude-image-generation

Configuration

API Keys

Set one or both as environment variables:

At least one key is required.

Model Selection

Override the default model per provider via environment variables:

Command-line --model flag on the scripts takes precedence over environment variables.

Display Size

Control the terminal image display dimensions (in pixels):

These apply to inline display (iTerm2, Sixel) and tmux pane display.

Available Gemini Models

Available OpenAI Models

Available xAI Models

Usage

Slash Command

/generate-image a golden retriever in a field of sunflowers
/generate-image --edit ./photo.png remove the background and make it transparent

The command prompts you to select a provider (Gemini, OpenAI, xAI, or all in parallel) and an output path.

Agent (Automatic)

The image-generator agent triggers automatically when conversation context involves image creation. It handles provider selection, parallel generation, and result delivery without requiring the slash command.

Direct Script Usage

Scripts are located in scripts/ and can be invoked directly.

gemini.sh

# Generate
bash scripts/gemini.sh \
  --mode generate \
  --prompt "a mountain at sunset" \
  --output ./mountain.png

# Generate with aspect ratio
bash scripts/gemini.sh \
  --mode generate \
  --prompt "a wide landscape" \
  --output ./landscape.png \
  --aspect-ratio 16:9

# Edit
bash scripts/gemini.sh \
  --mode edit \
  --prompt "add snow to the peaks" \
  --input-image ./mountain.png \
  --output ./snowy.png

# Generate at 4K with thinking mode
bash scripts/gemini.sh \
  --mode generate \
  --prompt "a detailed sci-fi cityscape" \
  --output ./city.png \
  --image-size 4K \
  --thinking-level High

# Generate with Google Search grounding
bash scripts/gemini.sh \
  --mode generate \
  --prompt "Search for the latest SpaceX Starship and draw it at sunset on the launch pad" \
  --output ./starship.png \
  --search-grounding

# Use a specific model
bash scripts/gemini.sh \
  --mode generate \
  --prompt "quick sketch" \
  --output ./sketch.png \
  --model gemini-3-pro-image-preview

Flags:

openai.sh

# Generate
bash scripts/openai.sh \
  --mode generate \
  --prompt "a mountain at sunset" \
  --output ./mountain.png

# Generate with options
bash scripts/openai.sh \
  --mode generate \
  --prompt "company logo on transparent background" \
  --output ./logo.png \
  --size 1024x1024 \
  --quality high \
  --background transparent

# Edit
bash scripts/openai.sh \
  --mode edit \
  --prompt "add snow to the peaks" \
  --input-image ./mountain.png \
  --output ./snowy.png

Flags:

xai.sh

# Generate
bash scripts/xai.sh \
  --mode generate \
  --prompt "a mountain at sunset" \
  --output ./mountain.png

# Generate with aspect ratio
bash scripts/xai.sh \
  --mode generate \
  --prompt "a wide landscape" \
  --output ./landscape.png \
  --aspect-ratio 16:9

# Edit
bash scripts/xai.sh \
  --mode edit \
  --prompt "add snow to the peaks" \
  --input-image ./mountain.png \
  --output ./snowy.png

# Generate at 2K resolution
bash scripts/xai.sh \
  --mode generate \
  --prompt "a cat in a tree" \
  --output ./cat.png \
  --resolution 2k

# Use the pro model
bash scripts/xai.sh \
  --mode generate \
  --prompt "a cat in a tree" \
  --output ./cat.png \
  --model grok-imagine-image-pro

Flags:

Note: For single-image edits, xAI ignores --aspect-ratio and uses the input image's ratio. Multi-image edits allow aspect ratio override (the script accepts up to 3 images; the API itself supports up to 5).

Reference Images and Multi-Image Composition

--input-image is repeatable on all three scripts. Passing more images than a provider supports exits with code 1 before any API call:

# Gemini: compose a new image from reference images (generate mode)
bash scripts/gemini.sh \
  --mode generate \
  --prompt "a product shot combining the chair from the first image with the fabric of the second" \
  --input-image ./chair.png \
  --input-image ./fabric.png \
  --output ./composite.png

# OpenAI: multi-image edit
bash scripts/openai.sh \
  --mode edit \
  --prompt "place the logo from the second image onto the mug in the first" \
  --input-image ./mug.png \
  --input-image ./logo.png \
  --output ./branded.png

# xAI: multi-image edit
bash scripts/xai.sh \
  --mode edit \
  --prompt "blend both scenes into one panorama" \
  --input-image ./left.png \
  --input-image ./right.png \
  --output ./panorama.png

# All providers in parallel (edit mode only)
bash scripts/run-all.sh \
  --mode edit \
  --prompt "combine these" \
  --input-image ./ref-a.png \
  --input-image ./ref-b.png \
  --output-base ./combined

Gemini's flat 14-image budget is best composed as up to 6 object + 5 character-consistency + 3 style-reference images. There is no API field to tag an image's role — the model infers it from the prompt, so state which images are objects, characters, or style references.

Notes:

• run-all.sh forwards every --input-image to each selected provider, but only in --mode edit. Gemini's generate-mode reference images are not forwarded through run-all — call scripts/gemini.sh directly for generate-with-references.
• dall-e-2 edits are a known limitation: the script rejects multiple images for dall-e-2, but single-image dall-e-2 edits also do not work — the script sends form fields only the gpt-image models accept.

Provider Comparison

Plugin Components

Development

Versioning

This plugin uses calendar versioning in YYYY.M.PATCH format (e.g., 2026.7.1). The version is tracked in both .claude-plugin/plugin.json and skills/image-generation/SKILL.md.

Testing

# Run all automated tests (requires bats)
./tests/run_tests.sh

# Or run bats directly
bats tests/

See TESTING.md for the full testing guide, including manual test procedures.

Architecture

The plugin is organized into Claude Code extension points:

.claude-plugin/plugin.json    -- Plugin identity and metadata
commands/                      -- Slash command definitions
agents/                        -- Autonomous agent definitions
skills/                        -- Skill knowledge and references
scripts/                       -- Shell scripts for API calls
tests/                         -- Automated tests (bats)

The scripts (gemini.sh, openai.sh, xai.sh) are standalone bash programs that handle API communication, base64 encoding/decoding, and error reporting. They are invoked by the command, agent, and skill layers. All three source display.sh which auto-detects the terminal and displays generated images using the best available method.

Terminal Image Display

When running inside tmux (including Claude Code sessions), provider images stream into a shared pane taking 30% of the terminal's longer axis, targeting the originating pane (via $TMUX_PANE). Every provider generating at that moment renders into that one pane. Direct calls to display_image / display_images outside a provider run still open a pane of their own: a bottom pane (-v split) for a single image, a vertical side pane (-h split, 30% width) for several. Panes use imgcat (iTerm2), kitten icat (Kitty), or a Sixel tool depending on the outer terminal. Press f to reveal in Finder, p to open in Preview, or Esc/Ctrl+D to close.

For parallel generation, use scripts/run-all.sh — a single shell that joins the streaming pane, exports DISPLAY_PANE_DIR, forks all providers with &, waits, and releases the pane.

Providers find that pane through a registry entry under $TMPDIR keyed by tmux session and window, so a provider launched on its own joins whatever is already streaming instead of splitting a pane of its own. The entry is a directory, making mkdir the atomic create-once lock: the winner opens the pane and publishes it, and callers that lose the claim wait briefly for that publication. Each participant holds a token under active/, and whoever drops the last one retires the entry and writes .done, so the pane closes once — after the last provider sharing it has finished. Sequential runs each get a fresh pane; concurrency is what makes providers share one. The watcher renders per-provider colored banners (blue/gray/red) with model + timing, plus an animated bottom spinner of pending providers shown until the first image renders (after which it stays silent, since further redraws would erase the accumulated inline images in tmux control mode). Provider scripts emit status events (querying / complete / error) via display_pane_status when running under DISPLAY_PANE_DIR; otherwise they fall back to display_image for direct terminal rendering.

Requirements

• curl -- HTTP requests to provider APIs
• jq -- JSON construction and parsing
• base64 -- Image data encoding/decoding (included in macOS and most Linux distributions)
• At least one API key: GEMINI_API_KEY, OPENAI_API_KEY, XAI_API_KEY, or GROK_API_KEY

Optional (for Sixel image display):

• img2sixel (from libsixel), chafa, or magick (ImageMagick 7) -- any one of these enables Sixel terminal display
• Install via: brew install libsixel, brew install chafa, or brew install imagemagick

License

MIT