Pixel Agents

Pixel Agents

A live pixel art visualization of Claude Code agents working in real time. Built for developers who want to show their AI workflow in an engaging, retro-game style.

Designed by **Vasyl Pavlyuchok** · [vasylpavlyuchok.com](https://vasylpavlyuchok.com) Sprites by [pablodelucca](https://github.com/pablodelucca/pixel-agents) (MIT)

---


What it does

• Reads Claude Code's session .jsonl files in real time
• Renders animated pixel art agents that react to what Claude is doing: reading, editing, running commands, thinking, spawning sub-agents
• Multi-agent support: each active agent gets its own character that walks to a desk and animates
• Broadcast toggle: control when the visualization is visible publicly

Requirements

• Docker + Docker Compose
• Claude Code running on the same machine or server

Quick start

git clone https://github.com/YOUR_USERNAME/pixel-agents.git
cd pixel-agents

Edit `docker-compose.yml` and set `CLAUDE_JSONL_DIR` to match where Claude Code writes its session files:

environment:
  - CLAUDE_JSONL_DIR=/dot-claude/projects/-root

Then:

docker compose up -d --build

Open `http://localhost:3000` — you'll see your agents live.

Configuration

See [CLAUDE.md](CLAUDE.md) for full setup instructions. You can also pass `CLAUDE.md` directly to Claude Code and ask it to configure everything automatically.

Tell Claude Code: "Read CLAUDE.md and help me set up Pixel Agents"

How it works

Claude Code writes conversation logs to `~/.claude/projects//`. This app mounts that directory read-only and tails the `.jsonl` files via a Server-Sent Events endpoint — no plugins, no hooks required.

Project structure

src/app/
├── api/pixel-agents/
│   ├── agents-stream/route.ts   ← SSE endpoint (reads Claude Code logs)
│   └── broadcast/route.ts       ← public visibility toggle
└── pixel-agents/
    ├── AgentDataCon