image-sprout

What this skill does

# 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:

```bash
npm install -g image-sprout
```

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

```bash
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:

```bash
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

```bash
# 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>
```

Top-level aliases:

```bash
npx image-sprout generate --project <name> --prompt "hero in neon rain"   # same as project generate
npx image-sprout analyze --project <name> --target both                    # same as project derive
```

## 5. JSON Output — the Agent Pattern

Always use `--json` for structured output:

```bash
npx image-sprout project show <name> --json
npx image-sprout project status <name> --json
npx image-sprout run latest --project <name> --json
npx image-sprout run list --project <name> --json --limit 5
```

Use `--value PATH` to pluck a single field:

```bash
npx image-sprout run latest --project <name> --json --value images[0].path
```

This is how agents hand image paths to downstream tools. Run images land in image-sprout's internal app data directory — use `run latest --json --value images[0].path` to get the path and leave what to do with it to the calling workflow.

## 6. Parallel-Safe Usage

`npx image-sprout project use <name>` sets a shared "current project" state on disk. In multi-agent workflows, this state can collide across concurrent processes. **Always pass `--project <name>` explicitly** — never rely on the current project shortcut.

## 7. Web UI — Agent Awareness

The web app runs over the same on-disk store as the CLI. Agents won't use it directly, but should surface it to users when interactive review is appropriate.

```bash
npx image-sprout web              # launches local app
npx image-sprout web --open       # also opens in default browser
npx image-sprout web --port 8080  # custom port (default: 4310)
```

Useful for:
- reviewing and comparing generated images visually
- setting up a project interactively before handing off to CLI/agent use
- iterating on outputs via the canvas interface

**Security: do not expose the web UI to the public internet.** The server has no authentication. Safe options are localhost only, or a private network like Tailscale. The risk is public internet exposure — LAN and tailnet access are fine.

## 8. Model Management

```bash
npx image-sprout model list
npx image-sprout model set-default google/gemini-3.1-flash-image-preview
npx image-sprout model add openai/gpt-5-image
npx image-sprout model restore-defaults
```

Default generation model is **Nano Banana 2** (`google/gemini-3.1-flash-image-preview`). Custom models must accept image input and produce image output via OpenRouter.

Guide derivation uses a separate configurable analysis model (default: `google/gemini-3.1-flash-image-preview`):

```bash
# Set a persistent analysis model
npx image-sprout config set analysisModel google/gemini-2.5-flash

# Override per-derive
npx image-sprout project derive <name> --target both --analysis-model google/gemini-2.5-flash
```