pixelagents

Watch your AI coding agents work — a live pixel-art floor, local-first.

Note: this is an independent weekend project, unaffiliated with pixel-agents — a more full-featured product in the same spirit (VS Code extension, office editor, asset packs) that predates this one. If you want the polished experience, use pixel-agents; this repo stays up as a small, zero-dependency, local-first alternative that was built almost entirely by the agents it visualizes.

Quickstart

npx github:YehudaLevi/pixelagents install-hooks
npx github:YehudaLevi/pixelagents

Open http://localhost:4242, start a Claude Code session, and watch yourself appear.

What you'll see

Each live Claude Code session gets a desk on the floor. The character's animation tracks what the agent is actually doing, in real time:

State	Trigger
Reading	Read / Grep / Glob
Bash	running a shell command
Editing	Edit / Write
Web	WebSearch / WebFetch
Minions	a subagent forks (SubagentStart)
Waiting-on-you glow	idle or permission prompt (optional 🔔 notification + 🔊 chime)
Sleeping	no events for 5 minutes
Confetti	a turn finishes

Try it without hooks

npx github:YehudaLevi/pixelagents --demo

Spins up the server with a synthetic event generator so you can see the floor in action before wiring up real hooks.

How it works

Claude Code hooks  →  ~/.pixelagents/events.jsonl  →  local server (SSE)  →  canvas floor

Hooks append one JSON line per event to a local file. A tiny local server tails that file and streams it to the browser over Server-Sent Events. The browser draws the floor. That's the whole pipeline: local-first, zero cloud, zero runtime dependencies.

Compatibility

Tested with Claude Code as of July 2026. The design degrades gracefully: unknown hook types become generic events, unknown tools render as a generic "working" animation, and the emitter always exits 0 — new Claude Code versions may add events we don't know yet, but they can't break your setup.

Other agents (Cursor, Codex, anything)

The floor isn't Claude-specific — every event carries a source field, and the emitter is a generic API: any tool that can run a shell command on events can join the floor today:

echo '{"hook_event_name":"PreToolUse","session_id":"my-session","cwd":"/path/to/repo","tool_name":"Edit","tool_input":{"file_path":"src/app.ts"}}' \
  | node "$(npm root -g)/pixelagents/bin/emit.js"

First-class adapters for other IDEs/agents are on the roadmap — open an issue for the one you want; demand decides the order.

Privacy

• Events carry tool names, file paths, and truncated commands only — never file contents, prompts, or environment values.
• Everything stays in ~/.pixelagents on your machine. Nothing leaves it.
• A broken visualizer can never break Claude Code: the emitter always exits 0 and runs in ~25ms.

Uninstall

npx github:YehudaLevi/pixelagents uninstall-hooks

Restores your ~/.claude/settings.json from the backup pixelagents made on install, removing only the entries it added.

Controls

• S / M / L — floor size
• Pan and zoom the canvas
• ⛶ — fullscreen
• / — search sessions
• 🔔 / 🔊 — toggle notifications and chime

Roadmap

Local is phase one. Next: Arena (one shared floor for your team, or a TV on the wall), waiting-time stats, replay, and an OBS overlay. See docs/roadmap.md.

Development

npm test        # vitest, 87 tests
npm run typecheck

See docs/architecture.md for how the pieces fit together.

License

MIT — see LICENSE.