crsolver / claude-pxl

# pxl
**Pixel art as code.** Write a compact `.px.js` file; get PNGs, sprite sheets with JSON, animated
GIFs, and a live browser viewer that replays the painting step by step as you save.
Built for AI agents (it ships as a ready-made agent skill) and pleasant
for people too. No runtime dependencies, no build step: just Node ≥ 22.18.
Every image above is generated from a file in `examples/`.
## Quick start
 [code] 
Or run it without cloning:
 [code] 
Write `art.px.js`:
 [code] 
 [code] 
 [code] 
## The live viewer
`pxl serve art.px.js` opens a viewer that rebuilds on every save and replays the asset you edited
op by op, so you (or whoever is watching an agent work) can see the art being painted. It also
writes the same `out/` files as `build`.
## Commands
 [code] 
`pxl` means `node bin/pxl.js` in a clone, or `npx github:crsolver/claude-pxl`. Art files can be `.js` or
`.ts` (`types/pxl.d.ts` gives editor completion).
## What's in the DSL
- **Palettes and ramps**: one-character color keys, built-in palettes (pico8, sweetie16, endesga32…),
 dark→light ramps that drive `shade()` / `light()`.
- **Sprites**: text grids, mirroring, auto-outline, palette-swap variants, flips/rotations, reusable
 `_parts`, `stamp`.
- **Primitives and brushes**: rects, lines, circles, polygons, gradients, dithering, noise, a built-in
 pixel font, `scatter` brushes, tilemaps, random groups with reproducible seeds.
- **Scenes**: layers, cast-shadow and light layers, per-layer PNG export.
- **Animation**: frames as patches over a base sprite → strips + JSON tags + GIF.
- **Lighting** (optional): lamps, glow, normal-based relief (see `lighting.md`).
- **Errors** point at `file:line:col` and the asset/layer/op path, with "did you mean…" hints.
Full API: `reference.md`. Agent workflow and essentials: `SKILL.md`.
## Use it with an AI agent
This repository is an agent skill: `SKILL.md` teaches the workflow (write → build → look at the
preview → patch), `reference.md` holds the full API, and `lighting.md` is loaded only when needed.
**Claude Code**: clone it into your skills folder, then ask Claude to draw something.
 [code] 
**Other agents** (Codex, Cursor, …): point them at `SKILL.md` and tell them the CLI is
`node /bin/pxl.js`.
Tip: ask the agent to start `pxl serve` so you can watch it paint in your browser.
## Development
 [code] 
 [code] 
In a clone the CLI runs the TypeScript sources directly. When installed as a package it runs
`dist/`, which `npm install` / `npm pack` generate via `scripts/build.js` (Node won't strip types
inside `node_modules`).
## License
MIT