README.md

June 14, 2026 · View on GitHub

pixtuoid

Your AI coding agents, visualized as pixel-art coworkers in a terminal office.

_{pixel + tui + (agent-)oid}

pixtuoid animated demo

🖥︎ Live demo ↗ · Architecture · Configuration · Contributing

Why?

Running several coding agents means alt-tabbing between terminals to find out who's stuck, who's waiting on a permission prompt, and who finished ten minutes ago. pixtuoid puts them all in one tiny pixel-art office you can watch from above — every session is a character at a desk: typing while it works, raising a ? when it needs you, dozing off when it's done.

A little bit Black Mirror, a little bit The Sims — and the most glanceable multi-agent dashboard you'll ever use.

Quick Start

Pick one — Homebrew on macOS, or npm on any OS:

Homebrew (macOS):

brew install IvanWng97/pixtuoid/pixtuoid

npm (any OS):

npm install -g pixtuoid

Then launch:

pixtuoid

Press c to open the Connection panel and connect your agent CLI (Claude Code, Codex, Antigravity, Reasonix, …) — pixtuoid wires up the integration for you, no separate install step. In another terminal, start that coding agent. A character walks in from the elevator within a second; disconnect in the same panel and it walks back out.

Keyboard shortcuts: q quit · p pause · c connections · t themes · Tab agent dashboard · ? help · ↑↓/jk/PgUp/PgDn floors · click to pin tooltip

More ways to install — Cargo, prebuilt binaries, and Debian .debs — are on the install guide ↗. Upgrading from ascii-agents? See docs/MIGRATION.md.

Features

	Feature	Description
🏢	Multi-agent office	Each agent session gets a desk; overflow agents auto-fill new floors
🛗	Multi-floor office	PageUp/PageDown/↑↓/jk to navigate floors with slide transition
🎭	Animated characters	Typing, waiting (`?`), sleeping (z's), walking with A*-routed pathfinding
💡	Per-tool monitor glow	Edit = blue, Bash = orange, Read = cyan — scannable at a glance
🎨	Per-agent identity	Deterministic shirt/hair/skin palette from session hash, 16 curated outfits
🌧️	Weather effects	Rain, storm, snow, fog, overcast, windy — cycles every 10 min + sunset golden hour
📊	Tooltip stats	Hover any agent to see session duration, tool call count, and active time %
🏷️	Furniture tooltips	Hover any item — desks, sofas, plants, vending machine, printer — to see its name
🐾	Office pets	A cat or dog (one per floor) roams desks, pantry, sofas; sleeps near idle agents. Click to pet — pixel-art hearts float up
☕	Coffee run	Idle agents visit the pantry, carry a cup back to their desk. Cup stays while you work; taken on exit
💬	Pantry chitchat	2+ idle agents at the same waypoint trigger speech bubbles with dev-humor snippets
🛡️	Hook-safe	The shim always exits 0 — a stuck visualizer can never block your agent

▶ See every feature live — floors, themes, weather, pets, the office tour →

Supported Tools

Tool	Runs on
Claude Code	macOS · Linux · Windows*
Codex CLI	macOS · Linux · Windows*

Also supported: Antigravity CLI, DeepSeek-Reasonix, CodeWhale, Copilot CLI, opencode, Cursor CLI.

→ Full tool × OS support matrix on the site

* experimental — limited testing, unsigned binaries.

Adding a new tool? Implement the Source trait — or, for a hook-only CLI, just a hook decoder + an install Target — then add a row to site/src/sources.json (its supported set is pinned to the code by a test). One file, one channel, done.

Themes & Configuration

Press t to cycle the built-in themes with live preview. Your choice persists across sessions:

built-in themes side by side

Settings live in ~/.config/pixtuoid/config.toml — theme, desk cap, custom pet names, and sprite packs. CLI flags override the file (pixtuoid run --theme dracula). See docs/CONFIGURATION.md for the full key reference (defaults, system-managed keys), the custom sprite-pack workflow, and logging / troubleshooting (the TUI writes warnings to ~/.cache/pixtuoid/log) — or browse it live at /config.

How It Works

Agent CLIs emit events two ways — a hook shim (a 200ms fire-and-forget write to a Unix socket, or a named pipe on Windows, that can never block your agent) and JSONL transcript watching. Both feed one channel; a reducer folds events into office state; the renderer draws it as half-block pixel art. Three Rust crates, zero terminal deps in the core.

Full architecture with diagrams → · single source: docs/ARCHITECTURE.md

Contributing

PRs welcome — especially new themes and Source adapters for other agent CLIs (Cursor, and more). See CONTRIBUTING.md for the build/test workflow, conventions, the review process, and how to add a new agent CLI. Architecture and the load-bearing invariants live in CLAUDE.md.