Pixel Agents for Cursor

A Cursor IDE extension that turns your AI coding agents into animated pixel art characters in a virtual office.

This is a fork of Pixel Agents adapted for Cursor IDE. Each Cursor agent conversation 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.

Features

• One agent, one character — every Cursor agent conversation gets its own animated character
• Live activity tracking — characters animate based on what the agent is actually doing (writing, reading, running commands)
• Office layout editor — design your office with floors, walls, and furniture using a built-in editor
• Speech bubbles — visual indicators when an agent is waiting for input or needs permission
• Sound notifications — optional chime when an agent finishes its turn
• Sub-agent visualization — Task tool sub-agents spawn as separate characters linked to their parent
• Persistent layouts — your office design is saved and shared across Cursor windows
• Diverse characters — 6 diverse characters based on JIK-A-4, Metro City

Requirements

• Cursor IDE
• VS Code 1.107.0 or later (Cursor is based on VS Code)

Getting Started

Install from source

git clone https://github.com/yourusername/pixel-agents-cursor.git
cd pixel-agents-cursor
npm install
cd webview-ui && npm install && cd ..
npm run build

Then press F5 in Cursor to launch the Extension Development Host.

Usage

1. Open the Pixel Agents panel (it appears in the bottom panel area)
2. Start a new Cursor agent conversation — watch the character appear automatically
3. The character will react in real time to what the agent is doing
4. Click a character to select it, then click a seat to reassign it
5. Click Layout to open the office editor and customize your space

How It Works

Pixel Agents for Cursor watches Cursor's agent-transcripts JSONL files to track what each agent is doing. The transcripts are located in ~/.cursor/projects/<workspace>/agent-transcripts/. 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.

The 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.

Differences from Original Pixel Agents

This fork is adapted for Cursor IDE with the following changes:

• Automatic agent detection — agents are detected automatically from Cursor's agent-transcripts, no need to manually spawn terminals
• Cursor tool support — supports Cursor-specific tools like StrReplace, Shell, SemanticSearch, TodoWrite, etc.
• Simplified workflow — just start a Cursor agent conversation and the character appears automatically

Layout Editor

The built-in editor lets you design your office:

• Floor — Full HSB color control
• Walls — Auto-tiling walls with color customization
• Tools — Select, paint, erase, place, eyedropper, pick
• Undo/Redo — 50 levels with Ctrl+Z / Ctrl+Y
• Export/Import — Share layouts as JSON files via the Settings modal

The grid is expandable up to 64×64 tiles. Click the ghost border outside the current grid to grow it.

Office Assets

The office tileset used in this project is Office Interior Tileset (16x16) by Donarg, available on itch.io for $2 USD.

This 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:

npm run import-tileset

The 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.

Tech Stack

• Extension: TypeScript, VS Code Webview API, esbuild
• Webview: React 19, TypeScript, Vite, Canvas 2D

Known Limitations

• Agent detection — the extension scans for new agent transcripts every second, so there may be a brief delay before a new agent appears
• Heuristic-based status detection — Cursor'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) and may occasionally misfire
• macOS testing — this fork has been developed on macOS but may have issues on Windows or Linux

Credits

This is a fork of Pixel Agents by Pablo De Lucca, adapted for Cursor IDE.

Original project:

• Author: Pablo De Lucca
• License: MIT
• Repository: https://github.com/pablodelucca/pixel-agents

License

This project is licensed under the MIT License, same as the original Pixel Agents project.