Pixelsmith

A pixel-art sprite editor your AI agent can actually drive. Headless core, browser editor, MCP server — all rendering the same pixels.

Status: 0.1, prototype. The engine and the MCP server are solid and well tested — 256 tests across the three packages. The hand-drawing tools are thin next to Aseprite. Read What this is and isn't before you invest in it.

Not published to npm yet. The npx commands below are how it will be installed; until then, clone the repo and run the server from packages/mcp/dist/server.js.

What it does

Connect an agent over MCP and it can create a sprite, draw into it, animate it with keyframes or procedural motion styles, and export a GIF, APNG or packed spritesheet — seeing a PNG preview after every single step. That last part is the whole design: an agent that can look at its own output iterates dramatically better than one working blind.

Drop a reference photo in the editor and the agent can read the actual pixels through an MCP resource, so "make it look like this" has something real behind it.

Related MCP server: aseprite-mcp

60-second quickstart

npx pixelsmith-mcp

That starts the MCP server on stdio with a sandboxed workspace in ./pixelsmith-workspace. Point a client at it.

Until the package is published, run it from a clone instead:

git clone https://github.com/liamlz11/pixelsmith
cd pixelsmith
npm install
npm run build
node packages/mcp/dist/server.js

The client configs below then take "command": "node" and "args": ["/absolute/path/to/pixelsmith/packages/mcp/dist/server.js"].

Claude Code

claude mcp add pixelsmith -- npx -y pixelsmith-mcp

Claude Desktop — claude_desktop_config.json:

{
  "mcpServers": {
    "pixelsmith": {
      "command": "npx",
      "args": ["-y", "pixelsmith-mcp"],
      "env": { "PIXELSMITH_WORKSPACE": "/absolute/path/to/a/folder" }
    }
  }
}

Cursor — .cursor/mcp.json:

{
  "mcpServers": {
    "pixelsmith": { "command": "npx", "args": ["-y", "pixelsmith-mcp"] }
  }
}

Cline — in cline_mcp_settings.json:

{
  "mcpServers": {
    "pixelsmith": { "command": "npx", "args": ["-y", "pixelsmith-mcp"], "disabled": false }
  }
}

Any generic MCP client — command npx, args ["-y", "pixelsmith-mcp"], transport stdio.

Then ask for something:

Create a 32×32 knight sprite, give it a breathing idle, and export a GIF.

The editor

git clone https://github.com/liamlz11/pixelsmith
cd pixelsmith
npm install
npm run dev

Opens on http://localhost:5173. On Windows, double-clicking dev.bat does the same thing — it installs dependencies on first run, builds the core package, starts the server and opens a browser. It shares the MCP server's library when both are running, so you can watch an agent draw and take over with the mouse mid-sprite.

Tool reference

Resources: pixelsmith://project, pixelsmith://project/{id}, pixelsmith://project/{id}/reference/{refId}, pixelsmith://items.

Prompts: recreate-reference-as-sprite.

Every create/draw/transform/export tool returns a base64 PNG alongside its text.

Motion styles

breathe · bob · sway · walk · recoil · swing · float · pulse · shake

Each generates a transform track from a handful of numbers (amplitude, frequency, phase, easing). They stack with per-modifier weight, stay re-editable in the document, and bake down to plain keyframes when you want to hand-tune. shake runs off a seeded PRNG — the same seed always produces the same jitter, because nothing here may break determinism.

Configuration

Architecture

Three packages, one idea:

packages/core     headless. no DOM, no React. document model, compositor,
                  animation engine, encoders. this is the product.
packages/editor   browser UI. imports core.
packages/mcp      MCP server. imports the same core.

The editor and the MCP server never reimplement anything. A determinism test renders a document through the GUI path and the export path and asserts the RGBA buffers are byte-identical — that guarantee is why an agent can trust what it sees in a preview. See docs/architecture.md.

Examples

examples/ holds runnable agent scripts and one optional sample content pack:

• examples/scripts/generate-from-description.mjs — a character from a text prompt

• examples/scripts/walk-cycle-from-one-frame.mjs — animate a single drawing

• examples/scripts/batch-recolor.mjs — one sprite, N palettes

• examples/cyberlab-mentors/ — eleven example characters and a wardrobe of items cut out of them. Sample content, not part of the tool. Load with PIXELSMITH_EXAMPLES=examples/cyberlab-mentors/pack.json.

What this is and isn't

It is: a genuinely headless pixel-art engine with a well-shaped MCP surface. Deterministic. Every mutation returns a picture. References give a vision model real pixels to match. Animation is transform tracks and procedural motion, not a flipbook. Old documents keep opening — there are four schema versions and migrators for all of them.

It isn't: an Aseprite replacement. There are no linked cels, no free-transform, no tilemaps, no brush engine to speak of. Undo is per-document and in-memory. The editor is one dark theme with no customisation. If you want to draw pixel art by hand, buy Aseprite — it costs about as much as lunch and it is excellent.

Use it if you want an agent to make sprites, or you want a headless sprite engine to build on. Don't use it if you want a better mouse-driven drawing app.

Contributing

See CONTRIBUTING.md. Security issues: SECURITY.md.

Licence

MIT — see LICENSE.