PixelForge

A pixel-art studio for humans and AI agents. Draw sprites, tilesets and animations, rig them with bones, and export to GIF, spritesheets, or a game engine — all on top of one small, dependency-free engine that a person drives through a web GUI and an AI agent drives through MCP. Same engine, same files, same undo history.

v1.0 · PolyForm Noncommercial 1.0.0 (fork freely, never for money) · runs in the browser and in Node ≥ 20

What you can make

• Sprites & tilesets — pencil, line, shapes, bucket, gradient, colour replace, plus selections, symmetry, dithering and pixel-perfect strokes.
• Frame-by-frame animation — a timeline with tags, adjustable per-frame durations, onion skin, and live playback.
• Procedural animation — parametric generators (idle bob, blink, breathe, walk scaffold, attack, jump) that turn a static sprite into a starting animation you refine by hand.
• Skeletal rigging — give a multi-part sprite a bone hierarchy, bind parts to bones, keyframe poses into clips, then bake to frames or export the skeleton so a game engine animates it at runtime.
• Export anywhere — PNG, animated GIF/APNG, packed spritesheets with metadata, and ready-to-use targets for Godot, Unity, Phaser, PixiJS and Aseprite.

Two ways to use PixelForge

| | You are a person | You are (or you use) an AI agent | | --- | --- | --- | | Interface | The web editor (apps/web) | The MCP server (pixelforge-mcp) | | How | Point, click, draw, scrub the timeline | Call typed tools that map 1:1 to engine commands | | Guide | docs/user-guide.md | AGENTS.md + the Skills |

Both talk to the same @pixelforge/core engine. Every edit — a brush stroke in the GUI or a tool call from an agent — is the same plain-JSON command, so anything one side makes, the other can open, replay and undo.

Quick start

Prerequisites: Node.js ≥ 20.

Run the studio with one command

npx @wfontesd/pixelforge

That single command launches both halves of PixelForge:

• the web editor, opened in your browser, and
• the MCP server, served over HTTP at http://127.0.0.1:4321/mcp,

both bound to the same workspace (the current directory). A person draws in the browser while an AI agent connects over MCP — same engine, same files.

npx @wfontesd/pixelforge [start]                Launch the studio (web + MCP over HTTP)
  -w, --workspace <dir>   Folder documents/exports are confined to (default: cwd)
      --port <n>          HTTP port (default: 4321)
      --host <addr>       Bind address (default: 127.0.0.1)
      --no-open           Don't open the browser

Install the Skills for your agent

Skills are self-contained playbooks that teach an agent how to use the tools well. Install them for Claude Code, Codex and Opencode with:

npx @wfontesd/pixelforge install-skills          # all agents, into ./.claude, ./.codex, ./.opencode
npx @wfontesd/pixelforge install-skills --target claude --global   # ~/.claude/skills

Connect an AI agent (MCP)

Every agent spawns its own stdio server via npx @wfontesd/pixelforge mcp, or connects over HTTP to a running npx @wfontesd/pixelforge studio. Copy-paste configs for Claude Code, Codex and Opencode are in AGENTS.md. The fastest one — Claude Code, stdio:

claude mcp add pixelforge -- npx -y @wfontesd/pixelforge mcp --workspace .

Develop from a checkout

git clone https://github.com/Wfontesd/pixelforge.git
cd pixelforge
pnpm install
pnpm build
pnpm start                 # same as `npx @wfontesd/pixelforge`, from the checkout

→ Full walkthrough: docs/user-guide.md

Documentation

| Doc | For | Contents | | --- | --- | --- | | docs/user-guide.md | End users | Every panel, tool, the timeline, rigging and export — step by step | | AGENTS.md | AI agents & their operators | Register the MCP server, install Skills, the core loop, tool map | | packages/mcp/README.md | Agent integrators | Full MCP tool/resource reference and error codes | | docs/architecture.md | Contributors | The command/change/history design that ties it all together | | docs/animation.md · docs/performance.md · docs/plugins.md | Contributors | Deep dives on animation, performance, and the plugin system |

The Skills in skills/ are self-contained agent playbooks: pixelforge (draw & animate) and pixelforge-rigging (bones & skeletal animation), each with references and worked examples.

Packages

PixelForge is a pnpm workspace. Everything is built on a zero-dependency core.

| Package | What it is | | --- | --- | | @pixelforge/core | The engine: document model, command/undo system, compositor, and the rig/skeleton model. Zero dependencies; runs in browser and Node. | | @pixelforge/export | PNG/GIF/APNG encoders, spritesheet packing, and export targets for game engines (incl. rig export). | | @pixelforge/generators | Deterministic animation generators and the rig-bake operation. | | @pixelforge/mcp | The MCP server that exposes the engine to AI agents — pixelforge-mcp (stdio) plus the createServer used by the HTTP launcher. | | pixelforge | The npx @wfontesd/pixelforge launcher: serves the web studio + MCP over HTTP, runs the stdio MCP server, and installs the Skills. | | @pixelforge/sdk | One import for tool/plugin authors: SpriteBuilder, typed command constructors, definePlugin. | | @pixelforge/app | The web editor (React + Vite + Zustand). | | @pixelforge/plugin-example | A reference plugin: a custom command, export target and generator. |

The core idea

Every action is a serializable command — { type: 'draw.ellipse', payload: {…} }. Running a command produces fine-grained changes that each carry their own undo data. That single decision is what makes every edit — from the GUI, an agent, a plugin or a script — undoable, redoable, replayable, and observable, and what lets humans and agents collaborate on the very same document.

import { Engine } from '@pixelforge/core';

const engine = Engine.create({ name: 'hero', width: 32, height: 32 });

// The same JSON a GUI click, an MCP tool call, or a plugin would send.
// Layer and frame default to the first image layer / first frame.
engine.execute({
  type: 'draw.ellipse',
  payload: { color: '#6dc2ca', x: 4, y: 4, width: 24, height: 24, filled: true },
});
engine.execute({
  type: 'draw.rectangle',
  payload: { color: '#140c1c', x: 4, y: 4, width: 24, height: 24 }, // outline
});

engine.undo(); // every command is undoable
engine.redo();

Development

pnpm install
pnpm build        # build every package
pnpm test         # run the full test suite
pnpm typecheck
pnpm lint
pnpm tsx packages/core/examples/smoke.ts   # headless end-to-end demo

See docs/architecture.md for the design and CONTRIBUTING conventions in docs/ for the deeper reference material.

License

PolyForm Noncommercial License 1.0.0 © 2026 PixelForge contributors.

PixelForge is source-available and free forever for noncommercial use. You are explicitly allowed to use it, fork it, modify it, and share your changes — for personal projects, learning, research, hobby work, and by nonprofit, educational and government organizations.

You may not use it for a commercial advantage or for monetary compensation. In short: keep it open, keep it non-commercial — nobody gets to make money off it. If you ever need a commercial arrangement, it must come from the copyright holder as a separate grant.

This is a noncommercial license, not an OSI-approved "open source" license — because every OSI open-source license is required to permit commercial use, which is exactly what we forbid here. The source stays open and forkable; the money-making door stays shut.