PixelHand

Pixel art, placed with intent. Built for AI agents.

An open-source engine for creating sprites, animation, and game art through MCP, CLI, or JavaScript. Local and API-driven models work with palette-indexed pixels, editable text grids, and visual feedback. Every change can be inspected, revised, and saved as source.

Get started · Connect an agent · Documentation · Contribute

Made with PixelHand

The Starfall Archive · animated environment

A lantern-bearing traveler crosses an old stone bridge to an observatory above a sea of clouds. An original 384 × 224 scene, with a 48-color palette and eight ambient animation frames: falling water, drifting fireflies, and starlight.

Still image · Native pixels · Editable project and build notes · Authoring script

Rowan · eight-direction walk

An original 32 × 40 character with eight authored facings, four walk poses, layered limbs, and frame-by-frame review.

Contact sheet · Individual GIFs and audit results · Authoring script

Farmhouse · architectural study

A building study with material ramps, warm lighting, and editable pixel source.

Editable project · Authoring script

These examples were authored and iterated with the engine. They demonstrate the drawing workflow; they are not autonomous model benchmark results.

Related MCP server: pixelsmith

What you can build

The core has zero runtime dependencies. Projects store their art in ordinary files you can version, diff, and carry into another tool.

Get started

Requires Node.js 20.3 or newer and Git.

git clone https://github.com/SirLichDevCraft/PixelHand.git
cd PixelHand
node examples/lantern.js

This creates an original lantern project in out/lantern-example/, including saved pixel source, a PNG export, and review images. Open out/lantern-example/out/lantern.png to see the result. Supply a new destination for another run:

node examples/lantern.js /path/to/new-art-project
node src/cli.js help draw_named_map

No package installation or API key is needed for the authored example. To install CLI commands from this checkout, see the installation guide.

Connect an agent

PixelHand exposes a stdio MCP server. In Zed, add this to settings.json, replacing the path with your checkout. Windows paths can use forward slashes, for example C:/repos/PixelHand/src/mcp.js.

{
  "context_servers": {
    "pixelhand": {
      "command": "node",
      "args": ["/absolute/path/to/PixelHand/src/mcp.js"],
      "env": { "PIXELHAND_TOOLSET": "core" }
    }
  }
}

The compact core profile provides discovery and everyday editing. An agent can find specialist tools with tool_search, inspect their contracts with tool_help, and execute them through tool_call.

Start a new art project with project_init; resume one with project_open. Build from silhouette to detail, inspect the renders, and review every animation frame and facing before export.

For standalone model execution, configuration examples support Ollama, LM Studio, and compatible API endpoints. See local and API inference for setup, budgets, and recovery.

Development status

0.2.0-rc.1 · release candidate. Automated checks cover the engine, persistence, public interfaces, and provider adapters. Live local/API art-quality qualification remains open. Mechanical checks and recorded visual review are reported separately.

Release gates · Roadmap · Changelog · Architecture

npm test
npm run check
npm pack --dry-run

Free to use

The code, documentation, and original artwork in this repository are released under the MIT license. Use, modify, share, and sell them in personal or commercial projects, with no royalties, subscription, or expiry. Keep the license and copyright notice with copies or substantial portions you distribute.

PixelHand imposes no license or attribution requirement on new art you create with it. Reusing the included artwork follows its MIT terms. See asset provenance for how imported assets are tracked.