---
slug: "pixel-plugin"
source_type: "readme"
source_url: "https://cdn.jsdelivr.net/gh/willibrandon/pixel-plugin@main/README.md"
repo: "https://github.com/willibrandon/pixel-plugin"
source_file: "README.md"
branch: "main"
---
# Aseprite Pixel Art Plugin for Claude Code

Create, animate, and export pixel art using Aseprite through natural language and commands in Claude Code.

*Powered by [pixel-mcp](https://github.com/willibrandon/pixel-mcp) - a Model Context Protocol server for Aseprite.*

## Features

**Natural Language Pixel Art Creation**
- "Create a 64x64 Game Boy style sprite"
- "Draw a red circle with blue outline"
- "Make a 16x16 tile"

**Animation Support**
- "Add a 4-frame walk cycle"
- "Create an idle animation"
- "Set frame timing to 100ms"

**Advanced Techniques**
- Apply dithering patterns
- Optimize color palettes
- Add shading and antialiasing
- Use retro console palettes (NES, Game Boy, C64, PICO-8)

**Game-Ready Export**
- PNG, GIF, spritesheet formats
- JSON metadata for Unity, Godot, Phaser
- Pixel-perfect scaling (2x, 4x, 8x)
- Multiple spritesheet layouts

## How It Works

This plugin uses the [pixel-mcp](https://github.com/willibrandon/pixel-mcp) Model Context Protocol server to communicate with Aseprite. The MCP server provides 40+ tools for pixel art operations and is bundled with the plugin.

## Quick Start

### 1. Prerequisites

- [Aseprite](https://www.aseprite.org/) v1.3.0+ installed
- [Claude Code](https://claude.com/code) installed

### 2. Installation

**Option A: Via Claude Code (recommended)**

In Claude Code, run:
```
/plugin
```
Then:
1. Select "Add marketplace"
2. Enter: `willibrandon/pixel-plugin` (for GitHub) or `./path/to/local/marketplace` (for local)
3. Select "Browse and install plugins"
4. Find and install `pixel-plugin`

**Option B: From command line**

```bash
# Add the GitHub marketplace
claude plugin marketplace add willibrandon/pixel-plugin

# Install the plugin
claude plugin install pixel-plugin
```

**Option C: Local development/testing**

```bash
# Clone the repository
git clone https://github.com/willibrandon/pixel-plugin.git
cd pixel-plugin

# Add as local marketplace (from parent directory)
cd ..
claude plugin marketplace add ./pixel-plugin

# Install from local source
claude plugin install pixel-plugin@pixel-plugin
```

### 3. Setup

Configure Aseprite path (one-time setup):

```bash
/pixel-setup
```

The command will auto-detect your Aseprite installation. If not found, specify the path manually:

```bash
/pixel-setup /Applications/Aseprite.app/Contents/MacOS/aseprite
```

### 4. Create Your First Sprite

```bash
# Using slash commands
/pixel-new 64x64 gameboy
"Draw a character sprite"
/pixel-export png character.png

# Or natural language only
"Create a 32x32 Game Boy sprite of a character"
"Export it as character.png"
```

## Usage

### Slash Commands

| Command | Description | Example |
|---------|-------------|---------|
| `/pixel-new [size] [palette]` | Create new sprite | `/pixel-new icon nes` |
| `/pixel-palette <action> [args]` | Manage palettes | `/pixel-palette set gameboy` |
| `/pixel-export <format> [file]` | Export sprite | `/pixel-export gif anim.gif` |
| `/pixel-setup [path]` | Configure plugin | `/pixel-setup` |
| `/pixel-help [topic]` | Get help | `/pixel-help palettes` |

### Natural Language

The plugin responds to natural language requests:

**Creation:**
```
"Create a 64x64 RGB sprite"
"Make a 16x16 tile with NES palette"
"Start a new 128x128 canvas"
```

**Drawing:**
```
"Draw a red circle in the center"
"Fill the background with blue"
"Draw a pixelated tree"
```

**Animation:**
```
"Add 4 frames for a walk cycle"
"Create a 2-frame idle animation"
"Set all frame durations to 100ms"
```

**Advanced:**
```
"Apply Floyd-Steinberg dithering"
"Reduce to 16 colors"
"Add shading with light from top-left"
"Convert to PICO-8 palette"
```

**Export:**
```
"Export as PNG at 4x scale"
"Export as animated GIF at 12 FPS"
"Create a horizontal spritesheet"
"Export with Unity JSON metadata"
```

## Examples

### Example 1: Game Boy Character

```bash
/pixel-new 48x48 gameboy
"Draw a character sprite - round head, square body, stick limbs"
"Add a 2-frame breathing animation"
/pixel-export gif character-idle.gif fps=2
```

**Result:** Game Boy character with subtle idle animation.

### Example 2: NES Tile

```bash
/pixel-new tile nes
"Draw a brick wall pattern"
"Apply Bayer dithering for texture"
/pixel-export png brick-tile.png scale=4
```

**Result:** Retro NES-style brick tile, scaled 4x for modern displays.

### Example 3: Modern Pixel Art

```bash
/pixel-new 64x64
"Draw a detailed sword with silver blade and gold hilt"
"Add shading from top-left light source"
"Apply soft antialiasing to edges"
/pixel-export png sword.png scale=2
```

**Result:** Modern pixel art with shading and antialiasing.

### Example 4: Animated Sprite for Game

```bash
/pixel-new 32x32 pico8
"Draw a simple character"
"Create an 8-frame run cycle"
"Set frames to 80ms each"
/pixel-export json game-character.json format=unity
```

**Result:** `game-character.png` spritesheet + `game-character.json` ready for Unity import.

## Palette Presets

### Retro Consoles
- `nes` - 54-color NES palette
- `gameboy` - 4-color Game Boy green
- `gameboy-gray` - 4-shade grayscale
- `c64` - 16-color Commodore 64
- `cga` - 4-color IBM CGA
- `snes` - 256-color Super Nintendo

### Modern Palettes
- `pico8` - PICO-8 fantasy console (16 colors)
- `sweetie16` - Popular 16-color palette by GrafxKid
- `db16` - DawnBringer's 16 colors
- `db32` - DawnBringer's 32 colors

### Generic
- `retro16` - Generic 16-color retro
- `retro8` - Generic 8-color retro
- `grayscale4/8/16` - Grayscale palettes

## Export Formats

### Formats
- **PNG** - Single frame or current frame with transparency
- **GIF** - Animated GIF with loop and timing control
- **Spritesheet** - Multiple layouts (horizontal, vertical, grid, packed)
- **JSON** - Metadata for game engines (Aseprite, TexturePacker, Unity, Godot)

### Spritesheet Layouts
- `horizontal` - All frames in a row (web animations)
- `vertical` - All frames in a column
- `grid` - Optimal rows × columns (game engines)
- `packed` - Space-optimized (texture atlases)

### Scaling
- `scale=1` - Original size
- `scale=2` - 2x pixel-perfect
- `scale=4` - 4x pixel-perfect
- `scale=8` - 8x pixel-perfect

## Documentation

- [Skills Reference](https://github.com/willibrandon/pixel-plugin/tree/HEAD/skills/) - Detailed Skill documentation
- [Commands Reference](https://github.com/willibrandon/pixel-plugin/tree/HEAD/commands/) - Slash command documentation

## Troubleshooting

### "Aseprite not found" Error

Run setup command:
```bash
/pixel-setup /path/to/aseprite
```

Platform-specific paths:
- **macOS**: `/Applications/Aseprite.app/Contents/MacOS/aseprite`
- **Linux**: `/usr/bin/aseprite`
- **Windows**: `C:\Program Files\Aseprite\Aseprite.exe`

### "MCP server not responding"

1. Verify Aseprite is installed and accessible
2. Check configuration: `cat ~/.config/pixel-mcp/config.json`
3. Re-run setup: `/pixel-setup`
4. Check binary permissions: `chmod +x bin/pixel-mcp`

### "Export failed" or "File not found"

- Ensure sprite is created before exporting
- Check output path is writable
- Verify format is supported (png, gif, sheet, json)

See [Known Issues](https://github.com/willibrandon/pixel-plugin/blob/HEAD/docs/KNOWN_ISSUES.md) for additional troubleshooting information.

## Platform Support

- macOS (Intel and Apple Silicon)
- Linux (x86_64 and ARM64)
- Windows (x86_64)

## Requirements

- **Aseprite**: v1.3.0 or higher
- **Claude Code**: v1.0.0 or higher
- **pixel-mcp**: MCP server (bundled) - [Source](https://github.com/willibrandon/pixel-mcp)
- **Disk Space**: ~50MB for plugin and binaries

## Contributing

Contributions welcome! Please see [CONTRIBUTING.md](https://github.com/willibrandon/pixel-plugin/blob/HEAD/CONTRIBUTING.md) for guidelines.

1. Fork the repository
2. Create feature branch (`git checkout -b feature/amazing-feature`)
3. Commit changes (`git commit -m 'Add amazing feature'`)
4. Push to branch (`git push origin feature/amazing-feature`)
5. Open Pull Request

## License

This project is licensed under the MIT License - see [LICENSE](https://github.com/willibrandon/pixel-plugin/tree/HEAD/LICENSE) file for details.