• Screenshots
• About
• What's New
• Features
• Quick Start
• Prerequisites
• Installation
• Development
• Project Structure
• Troubleshooting
• Contributing
• Related Documentation

The Command Center gathers the boss of every live terminal into one cross-session office — at a glance you can see which terminals need you, which are working, and which are done:

Claude Office Visualizer is a real-time pixel art office simulation that visualizes Claude Code operations. Watch as a "boss" character (main Claude agent) manages work, spawns "employee" agents (subagents), and orchestrates tasks in an animated office environment.

The application was built with Next.js, PixiJS, FastAPI, and Zustand.

• Dependency refresh: All packages across backend, frontend, hooks, and the OpenCode plugin bumped to latest (FastAPI 0.137, Starlette 1.3, Next 16.2.9, React 19.2.7, pixi.js 8.19, and tooling) — supersedes dependabot PRs #47/#50
• Bug fixes: Command Center exit-loop (#49), a Starlette 1.3 type-check regression (added httpx2), and a latent hooks logging bug

For the full release history, see CHANGELOG.md.

• Command Center: New cross-terminal overview that gathers the boss (main agent) of every live session into a single pixel office — see at a glance what's finished, still running, or needs your attention. Reachable from the header (when ≥2 sessions are active) or the Building view's penthouse tile
• Scrollable Building View: The building cross-section now scrolls when the floor list is taller than the viewport
• Full-system QA + security hardening: 41 bug fixes (including a polling deadlock, a Docker blank-page fix, and a CORS preflight fix) plus per-session authorization guards and event-payload validation

For the full release history, see CHANGELOG.md.

• Multi-Floor Building Navigation: Browse a multi-story building with floor-level views, each with its own office layout and agents
• Settings Overhaul: New building configuration and consolidated general settings tabs
• Kanban Whiteboard Mode: 12th whiteboard mode showing task workflow in columns

Special thanks to @mjcadile (PR #20) for the multi-floor building navigation, floor/room routing, and live session counts that power this release.

• Pluralization Support (i18n): Count-based translations now correctly display singular/plural forms (e.g., "1 event" vs "5 events") in all supported languages
• Star History Chart: Repository growth visualization added to README

For the full release history, see CHANGELOG.md.

• Real-time Visualization: Watch Claude Code operations as they happen in an animated office
• Boss & Employee Agents: Main Claude agent as boss, subagents as employees
• Multi-Floor Building: Navigate a multi-story building with independent offices per floor, breadcrumb navigation, and automatic session switching

• Visual State Indicators: Working, delegating, waiting states clearly displayed
• Thought/Speech Bubbles: See agent activities and communications

• Command Center: Cross-terminal overview that gathers every live session's boss into one pixel office, with status columns (Needs-you, Working, Done, Ended) and A* pathfinding to free seats
• Multi-Mode Whiteboard: 12 display modes with keyboard shortcuts (0-9, T, B, K) - todo list, remote workers, tool usage pie chart, org chart, stonks, weather, safety board, timeline, news ticker, coffee tracker, heat map, kanban
• Background Task Tracking: Remote Workers display shows background task status in video-call-style tiles
• Context Window Tracking: Animated trashcan fills with paper as context increases
• Compaction Animation: Boss stomps on trashcan to compact context
• City Skyline Window: Real-time day/night cycle based on local time with animated drifting clouds
• Wall Clock: Click to cycle between analog and digital (12h/24h) display modes
• User Preferences: Settings persist across sessions via backend database

• Git Status Panel: See repository status in real-time
• Printer Station: Printer animates when Claude completes work that produces a report or document
• Random Quotes: Agents display random acceptance/completion quotes when receiving or turning in work
• Safety Sign: Tool counter tracks uses since last context compaction

• WebSocket Architecture: Real-time state updates from backend to frontend
• Extensible Design: Easy to add new visualizations and features
• Cross-Platform: Runs on Windows, macOS, and Linux

For the fastest setup, see the Quick Start Guide.

git clone https://github.com/paulrobello/claude-office.git
cd claude-office
make install-all
make dev-tmux

Then open http://localhost:3000 and run any Claude Code command to see it visualized.

• Python 3.13+
• Node.js 20+ (Bun auto-detected if available)
• uv (Python package manager)
• Claude Code CLI installed and configured, or OpenCode with Bun

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

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

# Install backend dependencies
cd backend && uv sync && cd ..

# Install frontend dependencies
cd frontend && bun install && cd ..

# Install hooks into Claude Code
make hooks-install

For AI-powered features like agent name generation and task summaries, create a .env file in the backend/ folder with your Claude Code OAuth token:

# Set up a long-lived authentication token (requires Claude subscription)
# This will prompt you to authenticate and display your token
claude setup-token

# Create the .env file with the token
echo "CLAUDE_CODE_OAUTH_TOKEN=your-token-here" > backend/.env

Without this token, the visualizer works fully but displays raw agent IDs instead of friendly generated names, and tool names instead of summarized tasks. The frontend displays AI status in the top right corner so you can verify if it's properly configured.

Recommended: Using tmux

make dev-tmux

Navigate between windows with Ctrl-b n (next) and Ctrl-b p (previous).

Alternative: Basic parallel mode

make dev

This fork adds support for OpenCode as an alternative to Claude Code CLI. The opencode-plugin/ directory contains a plugin that sends OpenCode lifecycle events to the same backend API.

make opencode-install

This builds the plugin, links it globally, and registers it in your ~/.config/opencode/opencode.json.

make opencode-uninstall

The plugin maps OpenCode events to claude-office backend events:

See Docker Guide for detailed configuration.

Once running, open http://localhost:3000 in your browser.

claude-office/
├── backend/               # FastAPI backend
│   ├── app/
│   │   ├── api/          # REST and WebSocket endpoints
│   │   ├── core/         # State machine, event processor
│   │   └── models/       # Pydantic models
│   └── pyproject.toml
├── frontend/             # Next.js + PixiJS frontend
│   ├── src/
│   │   ├── components/   # React/PixiJS components
│   │   ├── hooks/        # Custom React hooks
│   │   ├── stores/       # Zustand state stores
│   │   └── systems/      # Animation, pathfinding
│   └── package.json
├── hooks/                # Claude Code integration
│   ├── src/              # Hook implementation
│   ├── install.sh        # Hook installer
│   └── uninstall.sh      # Hook uninstaller
├── opencode-plugin/      # OpenCode integration
│   ├── src/              # Plugin TypeScript source
│   ├── install.sh        # Plugin installer
│   └── uninstall.sh      # Plugin uninstaller
├── scripts/              # Utility scripts
├── docs/                 # Documentation
└── Makefile              # Project orchestration

1. Check hooks are installed: make hooks-status
2. Enable debug logging: make hooks-debug-on
3. Watch logs: make hooks-logs-follow

1. Check WebSocket connection in browser dev tools (Network > WS)
2. Verify backend is running: http://localhost:8000/health
3. Check browser console for errors

1. Check backend logs in tmux window or terminal
2. Clear database and restart: make clean-db && make dev

Contributions are welcome! Please ensure that all pull requests:

1. Pass all checks: make checkall
2. Follow the existing code style
3. Include appropriate tests for new features
4. Update documentation as needed

• Quick Start Guide - Get running in under 5 minutes
• Architecture - System design, data flow, component details
• Whiteboard Modes - 12 display modes with keyboard shortcuts
• Docker Guide - Docker deployment and configuration
• AI Summary - AI-powered summary service documentation
• Backend README - Backend-specific setup
• Frontend README - Frontend-specific setup
• Hooks README - Hook installation details
• OpenCode Plugin - OpenCode integration plugin
• Scripts README - Testing and simulation scripts
• CLAUDE.md - AI assistant instructions for this project