image-sprout

image-sprout

Generate and iterate on images with consistent style and subject identity. Image Sprout turns reusable project context — reference images, derived guides, and persistent instructions — into repeatable outputs you can build on across runs.

Use this skill when:

• The user asks to generate images and wants results that stay consistent across multiple runs
• The user wants to iterate on outputs from a previous generation
• The user needs to set up or manage an image project with references or style context
• The workflow requires structured, scriptable image generation with --json output

1. Installation

Install globally from npm:

npm install -g image-sprout

Or run without installing — prefer this in Codex sandbox environments where PATH is unreliable:

npx image-sprout help

All examples below use npx image-sprout. Substitute image-sprout directly if you have a global install.

2. OpenRouter Key Setup

Image Sprout stores its OpenRouter key on disk. Set it once per machine:

npx image-sprout config set apiKey <your-openrouter-key>
npx image-sprout config show    # confirm key is set (does not reveal the raw key)

3. The Project Model

Three context layers drive every generation:

• Visual Style — consistent look and feel across outputs
• Subject Guide — consistent subject identity across outputs
• Instructions — persistent generation constraints (watermarks, framing, branding)

Two reference pools:

• Shared refs — drive both guides (default, simplest)
• Split refs — separate style and subject pools (advanced; use --role style or --role subject when adding)

Understanding this model prevents the most common agent mistake: generating without saved context and wondering why outputs are inconsistent.

4. Core CLI Workflow

# Create a project
npx image-sprout project create <name>

# Add references (3+ recommended; more refs = better derivation)
npx image-sprout ref add --project <name> ./ref1.png ./ref2.png ./ref3.png

# Optional: persistent instructions
npx image-sprout project update <name> --instructions "Watermark bottom-right: subtle."

# Derive guides from refs
npx image-sprout project derive <name> --target both   # or: style, subject

# Check readiness before generating
npx image-sprout project status <name> --json

# Generate (--count controls images per run: 1, 2, 4, 6; default is 4)
npx image-sprout project generate <name> --prompt "hero in neon rain"
npx image-sprout project generate <name> --prompt "hero in neon rain" --count 1

# Inspect results
npx image-sprout run latest --project <name> --json

# Delete a session and all its runs/images
npx image-sprout session delete --project <name> <session-id>