Pixel Agents — What It Is

Pixel Agents is a tool that turns the AI coding agents running in your terminal into animated pixel-art characters working in a tiny office. Instead of watching raw text scroll by, you see a little character walk to a desk, sit down, type when it's editing files, read when it's searching, and raise a visual flag when it's stuck waiting for your input.

Two Ways to Run It

The same codebase ships in two forms:

• VS Code extension — installable from the VS Code Marketplace or Open VSX. Agents launch into VS Code terminals; the characters appear in a panel beside the terminal.
• Standalone CLI — run npx pixel-agents from your project folder. It starts a local server and shows the same office in a browser. Useful for tmux, remote machines, and non-VS Code workflows.

Key Features

• One agent, one character — every Claude Code terminal 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 permission.
• Sound notifications — optional chimes when an agent finishes a turn or requests permission.
• Sub-agents and teams — ephemeral sub-agents and persistent Claude teammates appear as separate characters, including team roles and lifecycle changes.
• Persistent layouts — your office design is saved and shared across VS Code windows.
• Shared layout and assets — import/export layouts and load external character, pet, and furniture packs.
• Areas — paint named areas onto the office, map workspace folders to them, and new agents sit inside the areas mapped to their folder.
• Diverse characters — 6 built-in characters (based on a free character pack by JIK-A-4, Metro City).

Requirements

• Claude Code CLI installed and configured (this is the only AI agent supported today; Codex, Gemini, Cursor, and others are on the roadmap).
• VS Code extension: VS Code 1.105.0 or later.
• Standalone CLI: Node.js 20 or later.
• Windows, Linux, or macOS.

How It Works (Briefly)

Pixel Agents detects what Claude Code is doing through two paths:

1. Hooks mode (default) — a hook script receives Claude events like SessionStart, PreToolUse, PermissionRequest, and Stop, then sends authenticated events to any active Pixel Agents servers.
2. Heuristic mode (fallback) — when hooks aren't available, it infers agent status by scanning Claude's JSONL session transcripts under ~/.claude/projects/.

Both sources are normalized into a shared event model, the runtime updates a central state store, and the office renders through Canvas 2D with pathfinding and character state machines.

Important: Pixel Agents does not modify Claude Code itself. Its hook configuration lives under ~/.claude/, and its own persistent data lives under ~/.pixel-agents/.

Architecture

The codebase is split into four main parts:

• core/ — provider, adapter, transport, schema, and message contracts (no runtime side effects).
• server/ — shared Fastify server, agent runtime, persistence, Claude provider, transcript scanning, and standalone CLI.
• adapters/vscode/ — the VS Code adapter: terminal, persistence, and webview bridge.
• webview-ui/ — React 19, Vite, Canvas 2D, and adapter-specific transports for VS Code and browser WebSocket clients.

The design is agent-agnostic and editor-agnostic: a typed HookProvider interface defines the integration boundary, so adding a new AI tool is a single subdirectory of code.

Security Notes (from the README)

The standalone CLI prints a URL containing a ?token=. That token is a bearer capability — whoever holds it can approve hook installs and launch agents from anywhere the server is reachable. Treat the URL as a secret: don't paste it into shared channels, and note it lands in your browser history. The default bind address is 127.0.0.1; binding to 0.0.0.0 exposes the UI and WebSocket to the local network and should only be done on a trusted network.

License

MIT License.