SPA — Aseprite Automation for AI Agents

Simple. Stable. Congruent.

Create, edit, verify, and export pixel art and sprite animations with AI agents.

SPA brings Aseprite to your agent workflows through a CLI, Agent Skill, or MCP server. Keep editable Aseprite source files (.aseprite) alongside PNGs, GIFs, sprite sheets, and tile assets for your game.

Read this in: English · 简体中文

Quick start · Usage guide · Examples · MCP setup

TL;DR

Just tell your AI agent:

Install the SPA CLI with uv tool install --python 3.13 aseprite-automation, and install its Agent Skill with npx skills add aigengame/aseprite-automation --skill spa -g. Then read the skill, follow it to configure SPA for my Aseprite installation, and verify the setup with spa info.

A separate Aseprite installation is required. See Installation and Agent Skill for prerequisites and setup options. You can also use the CLI directly or connect an MCP client.

Contents

• Why SPA?
• What can you build?
• Installation
• Quick start
• Choose your integration
• Examples
• Documentation and support
• Contributing

Why SPA?

Simple to use. Stable in practice. Congruent with your creative vision.

• Keep your assets editable. Work with native Aseprite layers, frames, cels, and tags. Retain the source for later revisions alongside exports for your game.
• Control the animation. Set frame timing, position, opacity, and motion on existing cels. Use explicit requests to make repeatable workflow steps.
• Bring your own artwork. Prepare external PNGs with palette, transparency, size, and anchor choices, then import compatible images for animation.
• Check what changed. Inspect saved assets, validate expected facts, compare frames, and preview results. Structured results help agents handle failures.
• Choose your agent connection. Use shell commands, reusable Skill guidance, or an Aseprite MCP server with the same underlying operations.

SPA runs Aseprite in batch mode. You do not need to drive the editor UI for supported operations. Art direction, visual review, and downstream game integration remain part of your workflow.

What can you build?

Use spa --help and each command's --schema for your installation. spa info checks your Aseprite runtime; spa schema also reports unavailable native capabilities.

Installation

You need Python 3.13+, uv, and a separate Aseprite installation. SPA does not bundle the Aseprite executable.

The PyPI package is aseprite-automation; the command is spa.

Install from PyPI

uv tool install --python 3.13 aseprite-automation
spa version

Update an existing installation with uv tool upgrade aseprite-automation. For MCP, install the optional extra: uv tool install --python 3.13 'aseprite-automation[mcp]'. If spa is not on PATH, run uv tool update-shell and open a new shell.

You can also install a wheel from a GitHub Release with uv tool install --python 3.13 /absolute/path/to/the-wheel.whl.

Install the current development version

Install Git LFS, then run:

git clone --branch dev https://github.com/aigengame/aseprite-automation.git
cd aseprite-automation
git lfs install
git lfs pull
uv tool install --python 3.13 .
spa version

Git LFS retrieves the native probe fixtures and example assets. The development branch may include capabilities that are not in the latest release. For source development, use uv sync and uv run spa; see the usage guide.

Quick start

Point SPA at your Aseprite executable. On macOS, use the binary inside Aseprite.app/Contents/MacOS/, rather than the .app directory.

export SPA_ASEPRITE_EXECUTABLE="/absolute/path/to/aseprite"
spa info

Use a new working directory for these commands. They create a 32×32 sprite, draw a purple disk on a transparent layer, export a PNG, and check the saved dimensions. Existing destinations are refused.

1. Create an editable source.

spa sprite create --input-json '{
  "target_sprite_file":"canvas.aseprite","overwrite":false,
  "width":32,"height":32,"color_mode":"rgb",
  "initial_layer":{"kind":"transparent"}
}'

2. Draw on the first layer and frame.

spa paint ellipse --input-json '{
  "source_sprite_file":"canvas.aseprite","target_sprite_file":"orb.aseprite",
  "in_place":false,"overwrite":false,
  "target":{"layer":{"layer_path":[1]},"frame_number":1},
  "coordinate_space":"image-pixel",
  "bounds":{"x":8,"y":8,"width":16,"height":16},"style":"filled",
  "brush":{"kind":"circle","size":1},
  "color":{"kind":"rgba","red":166,"green":104,"blue":255,"alpha":255},
  "ink":"simple","opacity":255
}'

3. Export the image.

spa export image --input-json '{
  "source_sprite_file":"orb.aseprite",
  "destination":{"path":"orb.png","if_exists":"fail"},"frame_number":1,
  "export_image_area":{"kind":"canvas"},"layer_composition":{"mode":"visible"},
  "composition_color_mode":"rgb","color_mode":"preserve",
  "color_profile":"preserve","transparency":"preserve"
}'

4. Check the saved source and view orb.png.

spa sprite validate --input-json '{
  "sprite_file":"orb.aseprite",
  "expected":{"width":32,"height":32,"color_mode":"rgb","frame_count":1}
}'

Commands return JSON by default; add --human for readable output. For validation, check valid, checks, and findings: status: success means the check ran. Visual quality still needs a look at the exported image.

Continue with the usage guide for animation, import, paint, color, tile, and export recipes. Use --help and --schema to discover fields without guessing.

Choose your integration

Agent Skill

From your consuming project, install the Skill with the Skills CLI. Node/npm is required.

npx skills add aigengame/aseprite-automation --skill spa

Add -g to install for your user across projects, as in the TL;DR above.

For a local development checkout, use:

npx skills add /absolute/path/to/aseprite-automation --skill spa

The Skills CLI manages installation and updates. The Skill reads the installed SPA help and schemas. It does not install SPA or Aseprite and does not add a separate compatibility or version manager.

MCP

Install the optional mcp extra as shown in Installation, then configure your client to launch the installed spa-mcp executable. Follow MCP setup for the stdio configuration.

Normal CLI use does not need the MCP extra. The MCP server uses the same operations and results; it does not keep an active sprite between calls.

Examples

Moonlit Spell Practice v2: imagegen artwork, Python motion assembly, and SPA animation and export. This preview uses exported PNG frames; the example also includes a playable Godot project.

Both wizard examples keep editable Aseprite sources and exported components. Their Godot projects use those assets for a spell-timing game: cast at a moving target, complete a round, and replay.

SPA authors and exports the animation; imagegen supplies v2's initial artwork. gda handles Godot verification. Each example records its preparation choices, validation evidence, and dogfooding feedback.

You can inspect the committed assets or open the Godot project without rebuilding all assets. Full rebuilds are optional local checks; see each example's instructions and testing guide.

Documentation and support

• Usage guide — recipes, runtime configuration, output handling, and current limits.
• Sprite sheet export — layouts, trimming, colors, and metadata.
• MCP setup — installation and client configuration.
• Issues — report a problem or request a capability.
• Milestones — planned work and delivery progress.
• Aseprite documentation — the editor, file formats, and native behavior.

When reporting a problem, include spa version, spa info, a minimal request, and the returned error. Attach a small reproducible asset when you can share it.

Contributing

Start with testing, architecture, and the domain model. The authority matrix routes product and implementation decisions.

SPA-owned code and documentation use the MIT license. Bundled third-party resources have their own notices. Aseprite is a separate product with its own license.