paulrobello/claude-office

Claude Office Visualizer – What It Is

Claude Office is an open‑source tool that turns the activity of Claude Code (a command‑line interface for Anthropic’s Claude model) into a playful, real‑time pixel‑art office simulation. A “boss” character represents the main Claude agent, while spawned “employee” agents show sub‑tasks. As you run Claude commands, the UI animates the agents moving around a multi‑floor building, updating their state, speech bubbles, and various dashboards.

The project bundles:

a FastAPI backend that receives events from Claude Code (or the OpenCode alternative) via HTTP/WebSocket,
a Next.js + PixiJS frontend that renders the office with React components and a 2‑D game‑engine style animation layer,
Zustand stores for fast state updates, and
hooks and an OpenCode plugin that inject the necessary event‑sending logic into the Claude CLI.

It’s essentially a monitoring dashboard for AI‑agent workflows, presented as an interactive game‑like visual.

Key Features (Jargon Light)

Feature	What It Does
Real‑time visualization	Shows Claude’s actions live in an animated office floor plan.
Boss & employee agents	Main Claude process appears as a boss; sub‑agents appear as employees doing tasks.
Multi‑floor building	Navigate separate office floors, each tied to a different Claude session.
Command Center	A cross‑session overview that gathers every live session’s boss into one “pixel office” with status columns (Needs‑you, Working, Done, Ended).
Whiteboard modes	12 visual modes (kanban, org chart, tool‑usage pie, timeline, etc.) selectable with keyboard shortcuts.
Context‑window tracker	An animated trash‑can fills as Claude’s context grows, and the boss can “compact” it.
Git status panel	Shows repository changes in real time.
AI‑enhanced names & summaries (optional)	With a Claude OAuth token the UI displays friendly agent names and task summaries instead of raw IDs.
Docker‑ready	One‑command Docker compose serves the UI on port 8050 and the API on 8000.
Cross‑platform	Runs on Linux, macOS, and Windows.

Quick Start (How to Get It Running)

# Clone and enter the repo
git clone https://github.com/paulrobello/claude-office.git
cd claude-office

# Install everything (backend, frontend, hooks)
make install-all

# Start the whole stack in a tmux session (recommended)
make dev-tmux

Open a browser to http://localhost:3000 to see the visualizer.

If you only want a single‑process run, make dev starts the backend and frontend in parallel without tmux.

Optional AI Enhancements

To get friendly names and AI‑generated task summaries, create a .env in the backend/ folder containing your Claude Code OAuth token:

claude setup-token   # obtains a long‑lived token
echo "CLAUDE_CODE_OAUTH_TOKEN=YOUR_TOKEN" > backend/.env

Without the token the visualizer still works, but agents appear with raw IDs.

Extending or Contributing

Add new visualizations – plug into the existing Zustand stores or create a new PixiJS system.
Support other backends – the architecture uses a simple event schema; you can write a new hook/plugin that posts the same JSON to the FastAPI endpoint.
Run tests – make checkall runs linting, type‑checking, and the full test suite (≈ 500 tests).
Docker – make docker-build && make docker-up builds a container and serves the UI at http://localhost:8050.

All contributions should pass the CI checks and include documentation updates.

Who Might Find This Useful?

Developers using Claude Code who want a visual cue of what the model is doing.
Researchers building multi‑agent LLM workflows and needing a quick way to see task delegation.
Educators looking for a fun demo of AI agents interacting in a shared environment.

Where to Learn More

Docs – docs/ contains a quick‑start guide, architecture overview, whiteboard‑mode reference, and Docker deployment instructions.
Demo video – linked in the README badge.
Source – the repo is split into backend/, frontend/, hooks/, and opencode‑plugin/ directories for clear separation of concerns.

TL;DR

Claude Office turns Claude Code’s internal events into a live, pixel‑art office simulation. Install with make install-all, run make dev-tmux, and point your browser at localhost:3000 to watch your AI agents work.