What is AssetForge?

AssetForge is not a tool you type commands into. It's a tool your IDE agent uses on your behalf.

You describe what you want in natural language. Your agent (Claude Code, Copilot, Cursor, Windsurf, Kiro...) reads the AssetForge skill files and translates your request into CLI commands. Sprites appear in your project.

You:    "I need a pixel-art fire mage, red robes, 64x64"
Agent:  → aforge sprite fire-mage "tall fire mage, crimson flowing robes..." --view front
Result: assets/sprites/fire-mage/fire-mage_front.png

The Flow

graph LR
    A[Developer] -->|natural language| B[IDE Agent]
    B -->|reads skills| C[aforge CLI]
    C -->|API call| D[OpenRouter]
    D -->|raw image| C
    C -->|post-process| E[Game-ready PNG]

Agent Skills

This is the core of AssetForge. The skills teach your IDE agent how to use the CLI. Without them, the agent doesn't know what commands exist.

AssetForge ships with skill files in templates/skills/. Drop them into your IDE's skills directory and your agent instantly knows every command, flag, and workflow.

| Skill | What it teaches the agent | |-------|--------------------------| | asset-forge | Full CLI reference — sprite generation, views, variants, edits, export, pixelize, palette | | asset-forge-init | Project setup — config wizard, API key, sprite conventions | | sprite-spec | Batch generation — define sprite rosters in JSON, process with checkpoints |

Quick Install

# From npm package → your IDE's skills folder
cp -r node_modules/@pokoion/assetforge/templates/skills/* .claude/skills/
# or: .cursor/skills/ , .kiro/skills/ , .opencode/skills/

Or with skills CLI:

npx skills add Pokoion/assetforge-skills

Design Checkpoint (Front-First Flow)

The agent skill enforces a mandatory design checkpoint:

1. Always generates front view first — regardless of what was requested
2. Shows the result and asks for approval before generating other views
3. User decides which additional views to generate
4. Each view shown individually with confirmation between them

This prevents wasting API calls on a design you don't like. The approved front becomes the visual reference for all other views, ensuring consistency.

Install

npm install -g @pokoion/assetforge

Requires Node.js >= 18. Verify installation:

aforge --version

Environment Setup

AssetForge uses OpenRouter for image generation (BYOK — Bring Your Own Key).

# Create .env in your game project root
echo "OPENROUTER_API_KEY=sk-or-v1-..." > .env
echo ".env" >> .gitignore

Your key never leaves your machine. All requests go directly to OpenRouter.

Output Gallery

Generated with aforge sprite via OpenRouter. Transparent PNGs, game-ready.

| Front | Side | Top-Down | Isometric | |:-----:|:----:|:--------:|:---------:| | | | | | | knight_front.png | knight_side-right.png | knight_top-down.png | knight_sw.png |

| Raw (magenta bg) | Chroma key | Despill | Autocrop | Final | |:----------------:|:----------:|:-------:|:--------:|:-----:| | | | | | |

How It Works

Descriptor Chain

Every asset has a deterministic identity stored in JSON. The agent reads these to understand project state.

assetforge.config.json    ← Project style, size, palette, provider
        |
sprites.json              ← Sprite-type conventions (outlines, lighting)
        |
warrior.json              ← Individual asset (description, views, reference)
        |
CLI flags                 ← Runtime overrides (--view, --edit, --variant)

Each level inherits from the one above. Inner overrides outer. CLI flags always win.

Post-Processing Pipeline

Every generated image goes through an automatic pipeline:

Raw PNG (magenta #FF00FF background)
  -> Chroma key removal (HSV flood-fill from borders)
  -> Despill (clean edge anti-aliasing artifacts)
  -> Autocrop (trim transparent padding)
  -> Resize (nearest-neighbor to target size)
  = Transparent, game-ready PNG

Reference Image System

After first generation, the sprite becomes its own visual reference:

• New views — existing image sent for style consistency
• Variants — base image + variant description = consistent evolution
• Edits — existing image + change instruction = surgical changes

Commands

Project Setup

| Command | Description | |---------|-------------| | aforge init | Interactive project setup wizard | | aforge init --from-json @file | Programmatic setup (for agents) | | aforge sprite init | Set sprite conventions | | aforge sprite init --from-json @file | Programmatic sprite conventions | | aforge config | Interactive provider/model config | | aforge config --list | Show available providers and models | | aforge config --provider <name> | Set image provider | | aforge config --model <name> | Set model for current provider | | aforge doctor | Health check (config, API key, dependencies) |

Sprite Generation

| Command | Description | |---------|-------------| | aforge sprite <name> "description" | Generate new sprite (first time) | | aforge sprite <name> --view <view> | Add a view to existing sprite | | aforge sprite <name> --variant <slug> "desc" | Create a named variant | | aforge sprite <name> --based-on <other> | New character inheriting style | | aforge sprite <name> --edit "change" | Modify existing sprite | | aforge sprite <name> --update-desc "text" | Update description (no generation) | | aforge sprite <name> --force | Regenerate, move old to history | | aforge sprite --from-spec file.json | Batch generate from spec file |

Utilities (Local, No API)

| Command | Description | |---------|-------------| | aforge pixelize <img> --size WxH | Convert any image to pixel art | | aforge pixelize <img> --size 16x16 --upscale 4 | Pixelize + scaled preview | | aforge palette extract <img> | Extract dominant colors from image | | aforge palette extract <img> --num-colors 16 | Extract N colors | | aforge export | Export all assets to ./export/ folder | | aforge export --zip | Export all assets as ZIP archive | | aforge export --output dist/sprites | Export to custom path |

Views

| View | Files Generated | API Calls | |------|----------------|-----------| | front | name_front.png | 1 | | top-down | name_top-down.png | 1 | | side-scroller | name_side-right.png + name_side-left.png | 1 (left is mirrored) | | isometric | name_sw.png, name_ne.png, name_nw.png, name_se.png | 1 (split + mirror) |

Full reference: docs/CLI_REFERENCE.md

Examples

First-Time Setup + Generation

You:    "Set up aforge for my dark fantasy RPG. Pixel art, 32x32, side-scroller."

Agent:  → Creates .env with your API key
        → aforge init --from-json @.aforge-init.json
        → aforge sprite init --from-json @.aforge-sprite-init.json
        "Project ready. What sprite do you want first?"

You:    "A skeleton warrior enemy"

Agent:  → aforge sprite skeleton "undead skeleton warrior, cracked bones visible
           through rusted chainmail, single glowing red eye in skull, broken sword
           held loosely, hunched posture" --view front
        "Here's the front view. Happy with it?"

You:    "Love it. Add side-scroller view."

Agent:  → aforge sprite skeleton --view side-scroller
        "Done:
           assets/sprites/skeleton/skeleton_side-right.png
           assets/sprites/skeleton/skeleton_side-left.png"

Variants & Edits

You:    "Make a fire variant of the skeleton"

Agent:  → aforge sprite skeleton --variant fire "burning skeleton, flames
           erupting from ribcage, ember particles, charred blackened bones"
        "Fire skeleton variant created."

You:    "The flames need to be bigger"

Agent:  → aforge sprite skeleton --variant fire --edit "larger more dramatic
           flames, fire engulfing the entire upper body"
        "Updated. Old version saved to history/."

Export Assets

You:    "Export all my sprites for the game build"

Agent:  → aforge export --output dist/sprites
        "Exported 24 assets to: dist/sprites"

You:    "Give me a ZIP I can send to the artist"

Agent:  → aforge export --zip --output review-assets.zip
        "Exported 24 assets to: review-assets.zip"

Output Structure

your-game/
├── .env                          ← API key (gitignored)
├── assetforge.config.json        ← Project config
└── assets/
    ├── manifest.json             ← All generated assets indexed
    └── sprites/
        ├── sprites.json          ← Sprite conventions
        └── knight/
            ├── knight.json       ← Descriptor (description, views, variants)
            ├── knight_front.png
            ├── knight_top-down.png
            ├── knight_side-right.png
            ├── knight_side-left.png      ← Auto-mirrored
            ├── history/                  ← Old versions (on --edit / --force)
            │   └── knight_front_20260510_120000.png
            └── variants/
                └── golden/
                    └── knight_golden_front.png

Providers

| Provider | Description | Auth | |----------|-------------|------| | OpenRouter | Multi-model BYOK gateway (recommended) | OPENROUTER_API_KEY | | Mock | Returns test PNG, no API calls | — |

Available Models (via OpenRouter)

| Model | Speed | Quality | Notes | |-------|-------|---------|-------| | google/gemini-3.1-flash-image-preview | Fast | Good | Recommended default | | openai/gpt-5-image-mini | Fast | Good | Alternative | | google/gemini-3-pro-image-preview | Slower | Best | Highest quality |

Switch models anytime:

aforge config --model google/gemini-3-pro-image-preview

Architecture

src/
├── cli.ts                ← Entry point, command registration
├── commands/
│   ├── init.ts           ← aforge init
│   ├── config.ts         ← aforge config
│   ├── doctor.ts         ← aforge doctor
│   ├── export.ts         ← aforge export
│   ├── pixelize.ts       ← aforge pixelize
│   ├── palette/
│   │   └── extract.ts    ← aforge palette extract
│   └── sprite/
│       ├── init.ts       ← aforge sprite init
│       └── generate.ts   ← aforge sprite <name>
├── descriptors/          ← Zod schemas + read/write for all JSON
├── prompts/              ← Descriptor chain → markdown prompt builder
├── providers/            ← Provider interface + OpenRouter implementation
├── postprocess/          ← Sharp pipeline (chroma key, autocrop, resize)
└── templates/            ← Isometric reference templates

Tech stack: TypeScript 5 • Commander • @clack/prompts • Sharp • Zod • Vitest

Contributing

git clone https://github.com/Pokoion/assetforge.git
cd assetforge
npm install
npm test

# Local development:
npm run dev -- sprite warrior "test" --view front
# or
npm run build && npm link
aforge sprite warrior "test" --view front

See CONTRIBUTING.md for detailed guidelines.

Roadmap

| Milestone | Status | Features | |-----------|--------|----------| | M0 | ✅ Done | Single-sprite generation, all views, variants, edits, config | | M1 | ✅ Done | Post-processing pipeline, isometric split, chroma key | | M2 | Planned | Tiles & tilesets | | M3 | Planned | Backgrounds (static + parallax) | | M4 | ✅ Done | Pixelize & palette tools | | M5 | ✅ Done | npm publish, standalone binaries, skill distribution | | M6 | Planned | Animations & spritesheets | | M7 | Planned | Sound effects (SFX) |

FAQ

No. The agent handles all commands. You just describe what you want. The skills teach the agent the full CLI reference.

AssetForge is free and open source. You pay only for the image generation API calls through OpenRouter (typically $0.01–0.04 per sprite depending on model).

Yes! All commands work directly in the terminal. The agent-first design just means the CLI output is optimized for machine parsing. Humans can use it fine.

Current AI image models can't reliably generate transparent backgrounds. AssetForge requests a solid magenta (#FF00FF) background and removes it via chroma key post-processing. The result is a clean transparent PNG.

OpenRouter provides a unified API for multiple model backends (OpenAI, Google, Stability, etc.) through a single key. One integration, many models. Switch models with one config change.

Set AFORGE_DEBUG=1 in your environment. This saves raw provider responses and intermediate images to .aforge-debug/ for inspection.

License

MIT © Jon Olea