pixel-plugin
Claude Code plugin for creating pixel art with Aseprite through natural language. Supports animation, retro palettes, dithering, and game engine export.
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Badge for your README
Markdown
[](/listings/willibrandon--pixel-plugin)HTML
<a href="/listings/willibrandon--pixel-plugin"><img src="/api/listings/willibrandon--pixel-plugin/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
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**
# Add the GitHub marketplace claude plugin marketplace add willibrandon/pixel-plugin # Install the plugin claude plugin install pixel-plugin
**Option C: Local development/testing**
# 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):
/pixel-setup
The command will auto-detect your Aseprite installation. If not found, specify the path manually:
/pixel-setup /Applications/Aseprite.app/Contents/MacOS/aseprite
4. Create Your First Sprite
# 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"
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
.claude-plugin/marketplace.json · Manifest · 14 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
- {
- "name": "pixel-plugin",
- "owner": {
- "name": "Brandon Williams",
- "url": "https://github.com/willibrandon"
- },
- "plugins": [
- {
- "name": "pixel-plugin",
- "source": "./",
- "description": "Create, animate, and export pixel art using Aseprite through natural language and commands"
- }
- ]
- }
README.md · README · 309 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
- # 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](skills/) - Detailed Skill documentation
- - [Commands Reference](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](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](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](LICENSE) file for details.
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.