Getting Started

pixelwright needs an agent that reads skills (Claude Code, or another agent pointed at the skills/ folder) and Python 3.9 or later with numpy and Pillow. artwright is optional.

Install in Claude Code

The marketplace is the repository itself. This installation recording used 0.8.2 with Claude Code 2.1.281, into an empty configuration folder:

$ claude plugin marketplace add m4bwav/pixelwright
Adding marketplace…SSH not configured, cloning via HTTPS: https://github.com/m4bwav/pixelwright.git
Refreshing marketplace cache (timeout: 120s)…
Cloning repository (timeout: 120s): https://github.com/m4bwav/pixelwright.git
Clone complete, validating marketplace…
Cleaning up old marketplace cache…
✔ Successfully added marketplace: pixelwright (declared in user settings)
$ echo $?
0
$ claude plugin install pixelwright@pixelwright
Installing plugin "pixelwright@pixelwright"...✔ Successfully installed plugin: pixelwright@pixelwright (scope: user)
$ echo $?
0

That 0.8.2 installation landed in Claude Code's plugin cache, under plugins/cache/pixelwright/pixelwright/0.8.2/ in the configuration folder (~/.claude unless CLAUDE_CONFIG_DIR says otherwise). That copy held the same files as the tag v0.8.2. The current release is v0.8.4; its command examples below were verified against the tagged source archive with --plugin, without reinstalling the plugin. Releases have no attached package asset.

Other agents (Copilot, Codex, Cursor, Gemini CLI): the README says to point them at the skills/ folder of a clone. That route was not tested for this wiki.

Python packages

pxw.py imports numpy and Pillow and nothing else outside the standard library (the model_rotate effect also needs tifffile, imported only when that effect runs).

python -m pip install numpy pillow

The earlier 0.8.2 examples ran on three set-ups, with the same output:

System	Python	numpy	Pillow
Windows 11	3.14.7	2.5.4	13.0.0 (the newest on 2026-10-26)
Windows 11	3.9.25	2.0.2	11.3.0 (the newest for Python 3.9)
Ubuntu on WSL	3.14.4	2.5.4	13.0.0

The 0.8.4 archive was verified on Windows with Python 3.14.6, numpy 2.5.2 and Pillow 12.3.0. Python 3.9 and Linux were not re-run for this update.

The earlier Python 3.9 run with Pillow 11.3.0 printed a DeprecationWarning on image writes. Its JSON on stdout matched the newer set-ups. The 0.8.4 Windows archive run emitted no such warnings.

Pillow 13.0.0 came out on 2026-10-16 and still accepts that argument: both test suites pass on it.

macOS was not run for this wiki; the repository's CI runs the tests on macOS with Python 3.9 and 3.14, and all six CI jobs passed on the release commit.

Check the set-up

doctor prints the versions, whether the packages loaded, where artwright's aw.py is, and the animation effects:

$ python pxw.py doctor
{
  "ok": true,
  "version": "0.8.4",
  "python": "3.14.6",
  "numpy": "2.5.2",
  "pillow": "12.3.0",
  "missing": null,
  "aw": null,
  "effects": [
    "arc",
    "assemble",
    "bands",
    "bend",
    "brighten",
    "buildup",
    "cart",
    "darken",
    "drone",
    "dust",
    "external",
    "fill",
    "glint",
    "model_rotate",
    "puffs",
    "pulse",
    "rotate",
    "scroll",
    "shift",
    "site",
    "sparks",
    "spill"
  ]
}
$ echo $?
0

Without numpy (this run used python -S, which hides installed packages) it says what is missing and exits 1:

$ python pxw.py doctor
{
  "ok": false,
  "version": "0.8.4",
  "python": "3.14.6",
  "numpy": null,
  "pillow": null,
  "missing": "No module named 'numpy'",
  "aw": null,

The version alone:

$ python pxw.py --version
0.8.4
$ echo $?
0

artwright

aw in the doctor output is artwright's aw.py. pxw.py looks for it in this order (from the source, find_aw):

1. the file named by PIXELWRIGHT_AW;
2. the file named by SPRITEWRIGHT_AW (the old name, still read);
3. the most recently modified artwright/scripts/aw.py under plugins in the folder CLAUDE_CONFIG_DIR names (since 0.6.2);
4. the same under ~/.claude/plugins.

With PIXELWRIGHT_AW pointing at artwright 0.7.0's aw.py (tag v0.7.0; 0.4.2 printed the same in every case on these pages):

  "missing": null,
  "aw": "<artwright>/skills/artwright/scripts/aw.py",

When it is not found, make and frames still run and the artwright gate says it was skipped:

    "aw_pixel": {
      "skipped": "artwright's aw.py not found (set PIXELWRIGHT_AW)"
    }

First runs

• A render to a sprite: Making pixel art.
• A still to an animation: Animating a sprite.

In Claude Code you can also just ask: the skills' descriptions name requests such as "make this real pixel art", "reduce to 16 colours" and "animate this building". Those agent routes were not run for this wiki; every example here calls pxw.py directly.

Uninstall

claude plugin uninstall pixelwright@pixelwright

Not run for this wiki.