Home

pixelwright

pixelwright is a Claude Code plugin for pixel art that an AI agent makes and animates in code. It has three agent skills and one Python script, pxw.py. The make half takes an image model's "pixel art" (thousands of colours, a blurred grid, a background) and turns it into a sprite with one pixel per block, a locked palette and hard alpha. The animate half moves parts of an existing still inside masks, so the rest frame is the still byte for byte and nothing outside the masks changes. Both halves end in gates: checks that print JSON and exit 1 when one fails.

It does not render images: an image generator such as ComfyUI or PixelLab does. It does not judge art: artwright's aw.py pixel does, and pixelwright calls it as a gate when it is installed. It does not import into an engine either. Version 0.6.0 was the first public release, tagged v0.6.0 on 2026-10-24; 0.6.1 followed the same day and changes only how make calls artwright; 0.6.2, also that day, prints a missing input file as a JSON error and finds artwright under CLAUDE_CONFIG_DIR. 0.6.3 added two kinds of item to the review page, and 0.7.0 a natural construction for assemble (both tagged 2026-10-25 UTC). Before 0.6.0 the plugin was called spritewright and did only the animation half; see Coming from spritewright.

0.8.2, tagged 2026-10-26, is the next release and takes in 0.7.1 to 0.8.1, which were never tagged. Its one behaviour change is that snap finds no grid when there are too few edges to tell a grid from chance (Making pixel art). Reports gain a few fields (enclosed_cleared from the background step; drawn_outside_silhouette and flicker_pixels in every animation's gates), and the rest is opt-in: enclosed background holes, linear-light dither, pixel-perfect corners, fog, the swap command, and new animation reports (Gates).

claude plugin marketplace add m4bwav/pixelwright
claude plugin install pixelwright@pixelwright

The smallest example

An image model's render of a mushroom: 132x132 pixels, 10,103 colours, drawn at 6x on a near-white ground and blurred. This recipe snaps it to its grid, clears the ground, reduces it to 8 colours and crops it to 32x32:

{"id": "mushroom", "input": "render.png", "palette": 8, "crop": {"pad": 1, "size": "32x32"}}

python pxw.py make recipe.json out

The gates at the end of the output:

  "gates": {
    "alpha_binary": true,
    "colours": 7,
    "colours_outside_palette": 0,
    "within_budget": true,
    "size_ok": true,
    "aw_pixel": {
      "skipped": "artwright's aw.py not found (set PIXELWRIGHT_AW)"
    }
  }
}

The render, and the 32x32 sprite the command wrote, both shown with nearest-neighbour scaling (the render at 2x, the sprite at 8x):

The run had no artwright installed, so the last gate was skipped. With artwright 0.4.1 or later installed, the same sprite passes its verdict too; Gates says which versions that needs.

How the pages show commands

pxw.py on these pages stands for skills/pixelwright/scripts/pxw.py inside the installed plugin, and sw.py for skills/pixelwright-animate/scripts/sw.py. Every output was printed by the released 0.8.2 plugin, installed with claude plugin install on 2026-10-26. Its inputs were pictures drawn in code: the mushroom render, a forge still, a gradient and a few small sprites. No real artwork was used. The program that ran them is in the repository at ai-docs/notes/2026-10-24-wiki-verify.py. Outputs on Windows (Python 3.14.7) and Linux (Python 3.14.4) were the same apart from the wording of a few error messages, noted where they appear.

Pages

• Getting started: install, Python packages, doctor, artwright, where the files land.
• Making pixel art: the make pipeline step by step on the render, and the recipe.
• Palettes: PICO-8, palette files, a set's own colours, extracting N colours, dithering.
• Animating a sprite: a brief, regions, frames, construction, the review page.
• Commands: every pxw.py command, its options, output fields, streams and exit codes.
• Gates: what each make and animation gate checks, failing examples, a CI check.
• Versions and upgrading: each release, and what changes when you move to 0.8.2.
• Coming from spritewright: what was renamed and what still works.
• FAQ: painted images, wandering grids, missing artwright, network use.
• Development: tests, CI, the rules in AGENTS.md, re-running this wiki's checks.

Elsewhere

• README and CHANGELOG
• Release v0.8.2
• Issues