claude-pxl README

The project's README from github.com/crsolver/claude-pxl. As one markdown file: README.md.

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.

Animated witch's cottage at night: bubbling cauldron, fireplace, cat and frog

Comet Repair shop scene Gull & Gill bait shop scene Moon Buns bakery scene Neon noodle bar scene

Animated glowing cave Animated cat Animated frog Animated clock

Every image above is generated from a file in examples/.

Quick start

git clone https://github.com/crsolver/claude-pxl.git
cd claude-pxl
node bin/pxl.js serve examples/shop.px.js     # live viewer at http://127.0.0.1:4321/

Or run it without cloning:

npx github:crsolver/claude-pxl build art.px.js

Write art.px.js:

pal({ k: "#1b1630", g: "#8ccf63", G: "#4c8a44", w: "#fff6e0", r: "#e2585e", R: "#a63a4c" })

// Write the left half; mirror it and outline it automatically.
sprite("slime", { mx: true, outline: "k" }, `
  ....ggg
  ..ggGGg
  .ggGwGg
  gggkwgg
  GGGGGGG`)
sprite("slime_red", { base: "slime", swap: { g: "r", G: "R" } })   // a recolor in one line

sheet("chars", ["slime*"], { pad: 1 })

node bin/pxl.js build art.px.js

out/sprites/slime.png  out/sprites/slime_red.png      the art, at 1x
out/chars.png          out/chars.json                 sprite sheet + TexturePacker-style JSON
out/_preview/*.png                                    upscaled previews with a pixel grid

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

pxl build <art.px.js> [--out DIR] [--only a,b] [--scale N] [--no-preview]
pxl serve <art.px.js> [--port 4321] [--out DIR | --no-out] [--no-preview]
pxl ascii <art.px.js> <name>     print an asset as palette keys with x/y rulers
pxl list  <art.px.js>            list assets, groups and sheets with source locations

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

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.

# all projects
git clone https://github.com/crsolver/claude-pxl.git ~/.claude/skills/pxl-pixel-art
# or just one project
git clone https://github.com/crsolver/claude-pxl.git .claude/skills/pxl-pixel-art

Other agents (Codex, Cursor, …): point them at SKILL.md and tell them the CLI is node <path to pxl>/bin/pxl.js.

Tip: ask the agent to start pxl serve so you can watch it paint in your browser.

Development

npm install        # dev only: typescript, @types/node
npm run check      # type check + tests
node scripts/gallery.ts   # regenerate docs/gallery

src/core/     engine, no Node APIs: image, palette + ramps, canvas ops, build, trace, project
src/node/     vm sandbox loader, PNG/GIF encoders, outputs, CLI, live server
src/viewer/   browser viewer (served type-stripped; no bundler)
types/        pxl.d.ts globals for editor support in .px.ts files
scripts/      build.js (dist/ for npm installs), gallery.ts
examples/     example art files
test/         node:test suites

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

claude-pxl (crsolver/claude-pxl)

npx
Searching Database…

246 ·GitHub
Claude-pxl
What is this?pxl lets you write pixel art as code: a compact .px.js file compiles to PNGs, sprite sheets with JSON, animated GIFs, and a live browser viewer that replays the painting step by step.
Is this a library or a CLI tool?It is a command-line tool built around a JS/TS DSL for describing pixel art, and the same repo doubles as a ready-made agent skill (SKILL.md) for AI coding agents.
How do I get it running?Run it without cloning via `npx github:crsolver/claude-pxl`, or clone the repo and run `node bin/pxl.js`; write an art.px.js file and use `pxl serve art.px.js` to see the live viewer.
Do I need anything besides Node installed?No, pxl has no runtime dependencies and no build step - just Node 22.18 or later.
Any gotchas when installing it as a package versus cloning?In a clone, the CLI runs the TypeScript sources directly; once installed as a package it runs the compiled dist/ folder, which npm install or npm pack generate via scripts/build.js, since Node cannot strip types inside node_modules.
Which coding agents can use it as a skill?Claude Code can load it by cloning it into the skills folder; other agents like Codex or Cursor can be pointed at SKILL.md and told the CLI is `node bin/pxl.js`.
What can the .px.js DSL actually draw?It supports palettes and color ramps, sprites with mirroring/auto-outline/palette-swap and flips/rotations, primitives like rects, lines, circles, polygons, gradients, dithering, noise, a built-in pixel font, scatter brushes and tilemaps, layered scenes with shadows and lights, and frame-based animation exported as strips, JSON tags, and GIFs.
What does the live viewer actually show?Running `pxl serve art.px.js` opens a browser viewer that rebuilds on every save and replays the edited asset operation by operation, so you can watch the art (or an AI agent) being painted step by step.
What is SKILL.md for?SKILL.md teaches an AI agent the write-build-preview-patch workflow for pxl, while reference.md documents the full API and lighting.md covers optional lighting features, loaded only when needed.
Can I write art files in TypeScript?Yes, art files can be .js or .ts, and types/pxl.d.ts provides editor autocompletion for the DSL.
What are similar projects?agent-sprite-forge, threejs-architecture-effects, procedural-film, Alvarmethod, nuwa-skill, brag, Waza, godogen
Which topics is it in?npx, pixel-art, gif, generative-art, zero-dependency, creative-coding, game-development, image-generation, skill, cursor, animation, agents
Creator
crsolver
Size
2.9 MB
Stars
246
Updated
CommitOct 15
Age
5d
Commits · 90 Days