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, takes in 0.7.1 to 0.8.1, which were never tagged. It makes snap find 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).

0.8.3 adds whole log courses and board-by-board plank roofs to natural construction plans. 0.8.4 fixes the flicker report for matched travelling pixels, including steps above 1 px per frame. It also documents flicker_at coordinates and warns that heavy fog with a sparse palette can flatten a sprite while passing every gate. Both releases are dated 2026-10-26. The 0.8.4 changes leave generated images unchanged; an animation with a flicker cap may now pass (Versions and upgrading).

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 plugin, and sw.py for skills/pixelwright-animate/scripts/sw.py. The command examples were refreshed against the released 0.8.4 tag archive on 2026-10-26, on Windows with Python 3.14.6, numpy 2.5.2 and Pillow 12.3.0. The installation transcript on Getting started retains its stated 0.8.2 provenance; the old-version comparison uses 0.7.0.

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 is in the repository at ai-docs/notes/2026-10-24-wiki-verify.py. Earlier 0.8.2 outputs on Windows and Linux agreed apart from a few version and error-message differences. Python 3.9 and Linux were not re-run for the 0.8.4 update.

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.4.
• 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.4
• Issues