---
title: "pxl"
url: https://manvsmidi.com/projects/pxl/
category: pixel-art
status: archived
date: 2026-03-17
tags: [pixel-art, ai, python, terminal]
related: [viper, blit, picrossh, society, shellscape]
---

# pxl

> A command-line pixel art generator. Describe a sprite in plain English and Claude returns it as a grid of hex colours, previewed in the terminal and saved as a transparent PNG.

Pixel art · Archived · 2026-03-17

- [Source](https://github.com/sadovsky/pxl)

pxl is a small Python CLI around one idea: skip image models and ask a language model for the pixels directly, as data.

```sh
pxl generate "a small red mushroom"
pxl generate "a blue spaceship" --size 32x32 --output ship.png
```

## How it works

The request goes to Claude with a system prompt that pins down two things.

**The format.** The model must reply with nothing but a JSON object holding `width`, `height` and a `pixels` array of `#RRGGBB` strings, with `#000000` reserved for background.

**The style.** The prompt reads like a short pixel art lesson: silhouette first, a one-pixel dark outline, a 6–14 colour palette, highlight and shadow from an upper-left light, no stray pixels, the subject centred and filling most of the canvas.

The response is pulled out with a balanced-brace scan, in case the model wraps it in anything, and then checked: dimensions must match, and every cell must be a valid hex colour. The result is drawn two rows per character with `▀` half-blocks in 24-bit colour, then written as an RGBA PNG. Black pixels become transparent, and each grid cell is scaled up to 16 physical pixels by default.

| Option | Default | |
|---|---|---|
| `--size WxH` | 16x16 | grid dimensions |
| `--output` | slug of the description | PNG path |
| `--scale N` | 16 | pixels per cell |
| `--no-preview` | off | skip the terminal render |

## Running it

Python 3.11+ and an Anthropic API key.

```sh
git clone https://github.com/sadovsky/pxl
cd pxl
pip install -e .
export ANTHROPIC_API_KEY=...
pxl generate "a golden coin"
```

## Connected projects

- [viper](https://manvsmidi.com/projects/viper/index.md): shared tags: terminal
- [blit](https://manvsmidi.com/projects/blit/index.md): shared tags: pixel-art
- [picrossh](https://manvsmidi.com/projects/picrossh/index.md): shared tags: terminal
- [Society](https://manvsmidi.com/projects/society/index.md): shared tags: terminal
- [shellscape](https://manvsmidi.com/projects/shellscape/index.md): shared tags: terminal