# 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](#what-this-is-and-isnt) 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.

## 60-second quickstart

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

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

```bash
claude mcp add pixelsmith -- npx -y pixelsmith-mcp
```

**Claude Desktop** — `claude_desktop_config.json`:

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

**Cursor** — `.cursor/mcp.json`:

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

**Cline** — in `cline_mcp_settings.json`:

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

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

| Tool | What it does |
| --- | --- |
| `list_characters`, `get_character` | Browse the library |
| `create_character`, `duplicate_character` | Make sprites |
| `set_pixels`, `draw_shape`, `import_item` | Draw |
| `add_layer`, `edit_layer`, `reorder_layers`, `merge_layers`, `add_layer_group`, `set_layer_blend` | Structure |
| `add_frame`, `set_frame_pixels`, `retime_frame`, `add_tag`, `set_tag_direction` | Timeline |
| `resize_canvas` | Grow, pad or crop the canvas — the fix for artwork clipped in exports |
| `add_transform_keyframe`, `apply_motion_style`, `bake_modifiers` | Animation |
| `apply_palette`, `add_swatch`, `add_ramp` | Colour |
| `add_reference`, `list_references`, `get_reference`, `update_reference`, `remove_reference` | References |
| `render_preview`, `export`, `export_spritesheet` | Output |
| `undo_character`, `redo_character`, `save_character` | History |

**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

| Variable | Default | Purpose |
| --- | --- | --- |
| `PIXELSMITH_WORKSPACE` | `./pixelsmith-workspace` | The only place on disk the server touches |
| `PIXELSMITH_LIBRARY_DIR` | `<workspace>/library` | Where documents are stored |
| `PIXELSMITH_OUTPUT_DIR` | `<workspace>/output` | Where exports are written |
| `PIXELSMITH_INPUT_DIR` | `<workspace>/input` | The **only** directory reference images may be read from |
| `PIXELSMITH_EXAMPLES` | unset | Path to an example pack JSON to preload |
| `PIXELSMITH_MAX_CANVAS` | `512` | Max canvas edge, in pixels |
| `PIXELSMITH_MAX_CELLS` | `262144` | Max total canvas cells |
| `PIXELSMITH_MAX_FRAMES` | `256` | Max frames per document |
| `PIXELSMITH_MAX_LAYERS` | `64` | Max layers per document |
| `PIXELSMITH_MAX_DOC_BYTES` | `33554432` | Max document size on disk |
| `PIXELSMITH_MAX_CALLS_PER_MIN` | `600` | Tool-call rate limit |

## 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](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](CONTRIBUTING.md). Security issues: [SECURITY.md](SECURITY.md).

## Licence

MIT — see [LICENSE](LICENSE).