PixelForge

Why PixelForge

• True pixels — indexed grid + palette, the same cells agents and humans edit
• Agent-first — external agents (Cursor, Codex, Claude Code, …) call local pixelforge; the in-app one-turn panel is only a demo
• Engine-ready export — PNG sequences, sprite sheets, atlas JSON, validation gates
• Not a full Aseprite clone, not diffusion fake-pixel, not a full game engine

Status: early / WIP. Prebuilt CLI v0.1.0-rc.5 is a prerelease. Longer vision & L4 framing: docs/vision.md. Honest bounds: docs/known-limits.md.

Quick start

Installers put pixelforge in ~/.pixelforge/bin. Use the rc.5 tag (not latest) until a stable release ships.

curl --proto '=https' --tlsv1.2 -LsSf \
  https://github.com/starcloud530/pixelforge-ai/releases/download/v0.1.0-rc.5/pixelforge-cli-installer.sh | sh

powershell -ExecutionPolicy Bypass -c \
  "irm https://github.com/starcloud530/pixelforge-ai/releases/download/v0.1.0-rc.5/pixelforge-cli-installer.ps1 | iex"

pixelforge --version
pixelforge new --width 16 --height 16 --output hero.json
pixelforge preview --project hero.json --scale 4

Manual archives, platform notes, and source builds: Install docs · Releases

Site & documentation

Marketing landing:

https://starcloud530.github.io/pixelforge-demos/

Product docs (MkDocs Material on this repo’s Pages):

https://starcloud530.github.io/pixelforge-ai/

Topic	Link
Install & quick start	install
Agent skill / CLI recipes	agent-skill
Tool API catalog	tool-api
Export & engine import	export
Project manifest	project-manifest
Tech stack	tech-stack
Known limits	known-limits
Licensing	licensing

Markdown sources live under docs/. Local preview:

pip install -r requirements-docs.txt
mkdocs serve

If the docs URL 404s after merge to main, enable Pages once: Settings → Pages → Build and deployment → Source = GitHub Actions.

Agent skills

Product skills live in skills/<name>/SKILL.md. Creative skills follow the pixelforge index-color invariants first. A packaged pixelforge binary lists and reads those skills with pixelforge skills list and pixelforge skills read <name>. Command reference: agent-skill.

Skill	Role
pixelforge	Core CLI, Tool API, shortest edit path
pixelforge-draw	Silhouette → flats → detail
pixelforge-sprite-4dir	Four-direction idle + walk sheets
pixelforge-layers	body / gear / limbs
pixelforge-critique	Read-only defect list
pixel-art-craft	Walk, camera, and motion craft (public tutorial links)

Showcase media

CDN (do not commit large media into git):

• Four-direction walk GIF
• Hero before/after
• Seven-stage timeline
• Sheet assembly video

Marketing site: pixelforge-demos Pages. Replayable demos / curated runs: pixelforge-demos. Do not add an examples/ tree to this repository.

Development

Prebuilt users can skip this. Source / web shell / CI: dev-setup.

cargo test -p pixelforge-kernel
cargo test -p pixelforge-cli

License

Code: MIT OR Apache-2.0 (LICENSE, LICENSE-MIT, LICENSE-APACHE).
Demo / eval art licenses are declared in pixelforge-demos.
Dependency notes: docs/licensing.md.