pixtuoid

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

Quick Start · Features · Supported Tools · Themes & Configuration · How It Works

Why?

Running multiple AI agents in the terminal is like managing a sweatshop you can't see. They type, they wait, they finish — and you have no idea who's doing what unless you scroll through logs like a bureaucrat.

pixtuoid puts them all in a tiny pixel-art office you can watch from above. A little bit Black Mirror, a little bit The Sims — and somehow the most intuitive multi-agent dashboard you'll ever use.

Quick Start

brew install IvanWng97/pixtuoid/pixtuoid
pixtuoid install-hooks
pixtuoid

In another terminal, start a Claude Code session. A character walks in from the elevator within a second.

Keyboard shortcuts: q quit · p pause · t themes · ↑↓/jk/PgUp/PgDn floors · click to pin tooltip

Pre-built binaries

Download from GitHub Releases:

Cargo

cargo install pixtuoid

From source

git clone https://github.com/IvanWng97/pixtuoid && cd pixtuoid
cargo build --release

Features

Supported Tools

Adding a new tool? Implement the Source trait — one file, one channel, done.

Themes & Configuration

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

Settings are stored in ~/.config/pixtuoid/config.toml (respects $XDG_CONFIG_HOME):

theme = "cyberpunk"
max-desks = 8
pack-dir = "~/.config/pixtuoid/packs/robot"

CLI flags override config: pixtuoid run --theme dracula

Custom Sprite Packs

Create your own character sprites:

pixtuoid init-pack ./my-pack     # extract skeleton template
# edit the .sprite files in ./my-pack
pixtuoid validate-pack ./my-pack # check for missing animations
pixtuoid run --pack-dir ./my-pack

A robot pack ships as an example at sprites/robot/. See the sprite format docs for palette keys and animation requirements.

How It Works

CC tool call ──► CC fires hook ──► pixtuoid-hook (shim)
                                         │ JSON over Unix socket
                                         ▼
                                  /tmp/pixtuoid-{uid}.sock
                                         │
                       HookSocketListener ─────► ┐
                                                 │ (Transport, AgentEvent)
                       JsonlWatcher       ─────► ┤ shared mpsc channel
                                                 ▼
                       Reducer ──► SceneState (watch channel)
                                         │
                       TuiRenderer ──► draw_scene @ ~30fps
                       (pose → pixel_painter → RgbBuffer → half-block → ratatui)

Three Rust crates:

Migrating from ascii-agents (v0.3.0 → v0.4.0)

v0.4.0 renames the project from ascii-agents to pixtuoid — pix(el) + tu(i) + (agent-)oid.

What changed

Upgrade steps

1. Install the new version:

   brew untap IvanWng97/ascii-agents 2>/dev/null
   brew install IvanWng97/pixtuoid/pixtuoid
   # or: cargo install pixtuoid
   

2. Re-register hooks (replaces old ascii-agents-hook entries automatically):

   pixtuoid install-hooks
   

3. Migrate config (optional — only if you customized config.toml):

   mkdir -p ~/.config/pixtuoid
   mv ~/.config/ascii-agents/config.toml ~/.config/pixtuoid/config.toml
   

GitHub links: The old IvanWng97/ascii-agents URL automatically redirects to IvanWng97/pixtuoid. Existing bookmarks and stars carry over.

Contributing

See CLAUDE.md for architecture and conventions. PRs welcome — especially new themes and Source adapters for other agent CLIs (Codex, Cursor, Gemini).

Implement the Source trait and plug in via SourceManager::with_source():

#[async_trait]
pub trait Source: Send + 'static {
    fn name(&self) -> &str;
    async fn run(self: Box<Self>, tx: TaggedSender) -> anyhow::Result<()>;
}

Acknowledgments

Inspired by pixel-agents (VS Code), clawd-on-desk (desktop pet), and Claude Code's Buddy.

Support

If you enjoy pixtuoid, consider buying me a coffee :)

License

MIT