pixel

pixel is a CLI-native pixel art editor built for deterministic scripting, automation, and agent-friendly workflows.

It does not try to be a GUI clone of Aseprite. The goal of this base version is to provide a clean command-line substrate for creating, modifying, versioning, and rendering pixel art projects through stable JSON or DSL commands.

What This Project Does

• Creates transparent .pixel/ project directories instead of opaque binary blobs
• Stores edit history as replayable command batches
• Supports layers, visibility, opacity, undo/redo, and PNG-backed storage
• Accepts structured JSON edit batches for automation and agent use
• Includes a small text DSL for human-readable command sequences
• Imports regular images into pixel projects
• Renders PNG output and terminal previews without any GUI dependency

Why It Exists

Most pixel art tools are GUI-first. They may expose scripting or export commands, but they are not designed around machine-readable editing contracts.

pixel takes the opposite approach:

• the project format is inspectable
• the edit protocol is explicit
• the CLI is the primary interface
• rendering is deterministic

That makes it useful for:

• scripted asset generation
• reproducible pixel art pipelines
• tool integration
• AI/agent experiments that need a controllable editor, not a black box

Core Commands

pixel init hero.pixel --size 32x32
pixel import reference.jpg --project portrait.pixel --size 96x96
pixel inspect hero.pixel --json
pixel exec hero.pixel --ops ops.json --dry-run
pixel exec hero.pixel --dsl edits.dsl
pixel render hero.pixel --output hero.png --scale 8
pixel preview hero.pixel --ansi
pixel undo hero.pixel --steps 1
pixel redo hero.pixel --steps 1

Project Format

Each project is a directory with a transparent layout:

• manifest.json
• palette.json
• history.ndjson
• layers/*.png
• snapshots/*.json

This makes projects easier to inspect, diff, recover, and process programmatically.

Editing Model

All changes flow through a typed OperationBatch.

Examples of supported operations include:

• set_pixel
• draw_line
• draw_rect
• fill_rect
• flood_fill
• replace_color
• add_layer
• rename_layer
• set_layer_visibility
• set_layer_opacity
• resize_canvas
• paste_image

Scope Of This Public Repo

This repository intentionally contains the basic editor/runtime layer:

• CLI editor
• import/export
• project storage
• deterministic raster operations

It does not include the later experimental research stack for staged planning, critique, search, and Codex-driven orchestration.

Development

cargo test

The integration tests cover:

• project init / exec / render
• DSL execution
• undo / redo
• JPEG import