Pixel Agents

1# Pixel Agents
2 
3A VS Code extension that turns your AI coding agents into animated pixel art characters in a virtual office.
4 
5Each Claude Code terminal you open spawns a character that walks around, sits at desks, and visually reflects what the agent is doing — typing when writing code, reading when searching files, waiting when it needs your attention.
6 
7This is the source code for the free [Pixel Agents extension for VS Code](https://marketplace.visualstudio.com/items?itemName=pablodelucca.pixel-agents) — you can install it directly from the marketplace with the full furniture catalog included.
8 
9 
10![Pixel Agents screenshot](webview-ui/public/Screenshot.jpg)
11 
12## Features
13 
14- **One agent, one character** — every Claude Code terminal gets its own animated character
15- **Live activity tracking** — characters animate based on what the agent is actually doing (writing, reading, running commands)
16- **Office layout editor** — design your office with floors, walls, and furniture using a built-in editor
17- **Speech bubbles** — visual indicators when an agent is waiting for input or needs permission
18- **Sound notifications** — optional chime when an agent finishes its turn
19- **Sub-agent visualization** — Task tool sub-agents spawn as separate characters linked to their parent
20- **Persistent layouts** — your office design is saved and shared across VS Code windows
21- **Diverse characters** — 6 diverse characters.
22 
23<p align="center">
24  <img src="webview-ui/public/characters.png" alt="Pixel Agents characters" width="320" height="72" style="image-rendering: pixelated;">
25</p>
26 
27## Requirements
28 
29- VS Code 1.109.0 or later
30- [Claude Code CLI](https://docs.anthropic.com/en/docs/claude-code) installed and configured
31 
32## Getting Started
33 
34If you just want to use Pixel Agents, the easiest way is to download the [VS Code extension](https://marketplace.visualstudio.com/items?itemName=pablodelucca.pixel-agents). If you want to play with the code, develop, or contribute, then:
35 
36### Install from source
37 
38```bash
39git clone https://github.com/pablodelucca/pixel-agents.git
40cd pixel-agents
41npm install
42cd webview-ui && npm install && cd ..
43npm run build
44```
45 
46Then press **F5** in VS Code to launch the Extension Development Host.
47 
48### Usage
49 
501. Open the **Pixel Agents** panel (it appears in the bottom panel area alongside your terminal)
512. Click **+ Agent** to spawn a new Claude Code terminal and its character
523. Start coding with Claude — watch the character react in real time
534. Click a character to select it, then click a seat to reassign it
545. Click **Layout** to open the office editor and customize your space
55 
56## Layout Editor
57 
58The built-in editor lets you design your office:
59 
60- **Floor** — Full HSB color control
61- **Walls** — Auto-tiling walls with color customization
62- **Tools** — Select, paint, erase, place, eyedropper, pick
63- **Undo/Redo** — 50 levels with Ctrl+Z / Ctrl+Y
64- **Export/Import** — Share layouts as JSON files via the Settings modal
65 
66The grid is expandable up to 64×64 tiles. Click the ghost border outside the current grid to grow it.
67 
68### Office Assets
69 
70The office tileset used in this project and available via the extension is **[Office Interior Tileset (16x16)](https://donarg.itch.io/officetileset)** by **Donarg**, available on itch.io for **$2 USD**.
71 
72This is the only part of the project that is not freely available. The tileset is not included in this repository due to its license. To use Pixel Agents locally with the full set of office furniture and decorations, purchase the tileset and run the asset import pipeline:
73 
74```bash
75npm run import-tileset
76```
77 
78Fair warning: the import pipeline is not exactly straightforward — the out-of-the-box tileset assets aren't the easiest to work with, and while I've done my best to make the process as smooth as possible, it may require some manual tweaking. If you have experience creating pixel art office assets and would like to contribute freely usable tilesets for the community, that would be hugely appreciated.
79 
80The extension will still work without the tileset — you'll get the default characters and basic layout, but the full furniture catalog requires the imported assets.
81 
82## How It Works
83 
84Pixel Agents watches Claude Code's JSONL transcript files to track what each agent is doing. When an agent uses a tool (like writing a file or running a command), the extension detects it and updates the character's animation accordingly. No modifications to Claude Code are needed — it's purely observational.
85 
86The webview runs a lightweight game loop with canvas rendering, BFS pathfinding, and a character state machine (idle → walk → type/read). Everything is pixel-perfect at integer zoom levels.
87 
88## Tech Stack
89 
90- **Extension**: TypeScript, VS Code Webview API, esbuild
91- **Webview**: React 19, TypeScript, Vite, Canvas 2D
92 
93## Known Limitations
94 
95- **Agent-terminal sync** — the way agents are connected to Claude Code terminal instances is not super robust and sometimes desyncs, especially when terminals are rapidly opened/closed or restored across sessions.
96- **Heuristic-based status detection** — Claude Code's JSONL transcript format does not provide clear signals for when an agent is waiting for user input or when it has finished its turn. The current detection is based on heuristics (idle timers, turn-duration events) and often misfires — agents may briefly show the wrong status or miss transitions.
97- **Windows-only testing** — the extension has only been tested on Windows 11. It may work on macOS or Linux, but there could be unexpected issues with file watching, paths, or terminal behavior on those platforms.
98 
99## Roadmap
100 
101There are several areas where contributions would be very welcome:
102 
103- **Improve agent-terminal reliability** — more robust connection and sync between characters and Claude Code instances
104- **Better status detection** — find or propose clearer signals for agent state transitions (waiting, done, permission needed)
105- **Community assets** — freely usable pixel art tilesets or characters that anyone can use without purchasing third-party assets
106- **Agent creation and definition** — define agents with custom skills, system prompts, names, and skins before launching them
107- **Desks as directories** — click on a desk to select a working directory, drag and drop agents or click-to-assign to move them to specific desks/projects
108- **Claude Code agent teams** — native support for [agent teams](https://code.claude.com/docs/en/agent-teams), visualizing multi-agent coordination and communication
109- **Git worktree support** — agents working in different worktrees to avoid conflict from parallel work on the same files
110- **Support for other agentic frameworks** — [OpenCode](https://github.com/nichochar/opencode), or really any kind of agentic experiment you'd want to run inside a pixel art interface (see [simile.ai](https://simile.ai/) for inspiration)
111 
112If any of these interest you, feel free to open an issue or submit a PR.
113 
114## Contributions
115 
116See [CONTRIBUTORS.md](CONTRIBUTORS.md) for instructions on how to contribute to this project.
117 
118Please read our [Code of Conduct](CODE_OF_CONDUCT.md) before participating.
119 
120## Supporting the Project
121 
122If you find Pixel Agents useful, consider supporting its development:
123 
124<a href="https://github.com/sponsors/pablodelucca">
125  <img src="https://img.shields.io/badge/Sponsor-GitHub-ea4aaa?logo=github" alt="GitHub Sponsors">
126</a>
127<a href="https://ko-fi.com/pablodelucca">
128  <img src="https://img.shields.io/badge/Support-Ko--fi-ff5e5b?logo=ko-fi" alt="Ko-fi">
129</a>
130 
131## License
132 
133This project is licensed under the [MIT License](LICENSE).
134