---
slug: "claude-office"
source_type: "readme"
source_url: "https://cdn.jsdelivr.net/gh/paulrobello/claude-office@main/README.md"
repo: "https://github.com/paulrobello/claude-office"
source_file: "README.md"
branch: "main"
---
# Claude Office Visualizer

![CI](https://github.com/paulrobello/claude-office/actions/workflows/ci.yml/badge.svg)
![GitHub Release](https://img.shields.io/github/v/release/paulrobello/claude-office)
![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)
![GitHub](https://img.shields.io/badge/github-paulrobello%2Fclaude--office-blue?logo=github)
![Runs on Linux | MacOS | Windows](https://img.shields.io/badge/runs%20on-Linux%20%7C%20MacOS%20%7C%20Windows-blue)

[![Watch the demo](https://img.shields.io/badge/YouTube-Demo-red?logo=youtube)](https://youtu.be/AM2UjKYB8Ew)

## Table of Contents

* [Screenshots](#screenshots)
* [About](#about)
* [What's New](#whats-new)
* [Features](#features)
* [Quick Start](#quick-start)
* [Prerequisites](#prerequisites)
* [Installation](#installation)
* [Development](#development)
* [Project Structure](#project-structure)
* [Troubleshooting](#troubleshooting)
* [Contributing](#contributing)
* [Related Documentation](#related-documentation)

## Screenshots

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:

![Command Center](https://raw.githubusercontent.com/paulrobello/claude-office/main/screenshots/sc_command_center.png)

| | |
|---|---|
| ![Office View](https://raw.githubusercontent.com/paulrobello/claude-office/main/screenshot.png) | ![Multi-Floor Building](https://raw.githubusercontent.com/paulrobello/claude-office/main/screenshots/sc_floor_office.png) |
| ![Floor View](https://raw.githubusercontent.com/paulrobello/claude-office/main/screenshots/sc_floor_view.png) | ![Building Settings](https://raw.githubusercontent.com/paulrobello/claude-office/main/screenshots/sc_building_settings.png) |


## About

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](https://nextjs.org/), [PixiJS](https://pixijs.com/), [FastAPI](https://fastapi.tiangolo.com/), and [Zustand](https://github.com/pmndrs/zustand).

[!["Buy Me A Coffee"](https://www.buymeacoffee.com/assets/img/custom_images/orange_img.png)](https://buymeacoffee.com/probello3)

## What's New

### v0.24.1 (July 2026)

- **Bug fix — API URL env vars now respected everywhere.** The floor-config hook (`useFloorConfig.ts`) and the simulation scripts (`scripts/scenarios/_base.py`) hardcoded `http://localhost:8000`, so they silently broke when the backend ran on another port (e.g. 8000 was already in use). They now read `NEXT_PUBLIC_API_URL` and `CLAUDE_OFFICE_API_URL` like the rest of the stack; standard-port defaults are unchanged. Thanks [@rasulboliev](https://github.com/rasulboliev) ([PR #55](https://github.com/paulrobello/claude-office/pull/55)).

### v0.24.0 (July 2026)

- **⚠ Breaking — OpenCode plugin remote backend is now opt-in**: a non-localhost `CLAUDE_OFFICE_API_URL` is clamped to the local default unless `CLAUDE_OFFICE_ALLOW_REMOTE=1` is set (matching the Claude Code hooks; event payloads carry tool I/O and file paths). **If you point the plugin at a remote server, set `CLAUDE_OFFICE_ALLOW_REMOTE=1` or events silently post to localhost.**
- **Pluggable summary backend**: summaries now come from `SUMMARY_BACKEND` = `claude-cli` (default), any `openai`-compatible endpoint, or `disabled` — `CLAUDE_CODE_OAUTH_TOKEN` no longer required.
- **Performance & architecture**: per-frame agent writes batched into one store update per tick (header/sidebar/modals stop re-rendering at 60fps during movement); `gameStore` split into 9 Zustand slices; single-writer agent-state ownership retires the 3-second "stuck boss" watchdog. 67 of 69 audit findings resolved.

### v0.23.0 (July 2026)

- **Audit remediation (60 findings)**: Full security hardening (API key no longer disclosed over HTTP — delivered via `?token=` launch URL, `focus`/clipboard gated behind the key, git invocation hardening against hostile repos, Docker bound to loopback), a real CI workflow running `make checkall` across all four components, and the entire backend structural chain consolidated (single event-dispatch table, `ConnectionManager` moved to the domain layer with functional DI seams, `EventData` discriminated union, `BasePoller` framework, `main.py` split into middleware/migrate/websockets, bounded growth with idle eviction + replay pagination). +489 tests. See `CHANGELOG.md` and `AUDIT-REMEDIATION.md`
- **Code quality & docs**: 76 frontend characterization tests, `useWebSocketEvents` decomposed into pure transport + domain modules, the OpenCode plugin's session-tracking extracted into a tested `SessionTracker` with real ESLint, atomic `gameStore` dequeue, named constants, a fail-safe hooks installer that preserves user edits, `VERSION`/`__version__` derived via `importlib.metadata`, and `make bump-version` automation. API authentication, the `SERVE_STATIC` gate, Command Center architecture, and complete env-var tables documented

### v0.22.0 (June 2026)

- **Schedule editor cron helpers**: New pure `src/utils/cron.ts` utilities that round-trip between a friendly schedule editor and 5-field cron expressions (`timesToCron`, `intervalToCron`, `cronToEditor`)
- **Bug fixes**: Attention toast dismiss glyph rendered as raw source text instead of ✕ (#54), a Windows hook crash caused by a conflicting system OpenSSL, and dropped proxy/redirect support for remote `http://` backends (#53)

### v0.21.0 (June 2026)

- **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

### v0.20.0 (June 2026)

- **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

### v0.15.0 (May 2026)

- **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](https://github.com/mjcadile) ([PR #20](https://github.com/paulrobello/claude-office/pull/20)) for the multi-floor building navigation, floor/room routing, and live session counts that power this release.

### v0.14.0 (April 2026)

- **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](https://github.com/paulrobello/claude-office/blob/HEAD/CHANGELOG.md).

## Features

### Core Capabilities
- **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

![Multi-Floor Building](https://raw.githubusercontent.com/paulrobello/claude-office/main/screenshots/sc_floor_office.png)

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

### Advanced Features
- **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

![Settings](https://raw.githubusercontent.com/paulrobello/claude-office/main/screenshots/sc_general_settings.png)
- **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

### Technical Excellence
- **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


## Quick Start

For the fastest setup, see the [Quick Start Guide](https://github.com/paulrobello/claude-office/blob/HEAD/docs/guides/quickstart.md).

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

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

## Prerequisites

- Python 3.13+
- Node.js 20+ (Bun auto-detected if available)
- uv (Python package manager)
- Claude Code CLI installed and configured, **or** [OpenCode](https://opencode.ai) with Bun

## Installation

### Quick Start

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

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

### Manual Installation

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

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

# Install hooks into Claude Code
make hooks-install
```

### Enable AI Enhancements (Optional)

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:

```bash
# 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.

## Development

### Starting the Development Servers

**Recommended: Using tmux**

```bash
make dev-tmux
```

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

**Alternative: Basic parallel mode**

```bash
make dev
```

### Available Commands

| Command | Description |
|---------|-------------|
| `make dev` | Start backend and frontend in parallel |
| `make dev-tmux` | Start in tmux with separate windows (recommended) |
| `make dev-tmux-kill` | Kill the tmux session |
| `make checkall` | Run format, lint, typecheck, and tests |
| `make test` | Run all test suites without the other checks |
| `make simulate` | Run event simulation script |
| `make build-static` | Build frontend and copy to backend for standalone deployment |
| `make clean-all` | Remove all build artifacts and data |

### Hook Management

| Command | Description |
|---------|-------------|
| `make hooks-install` | Install hooks into Claude Code |
| `make hooks-uninstall` | Remove hooks from Claude Code |
| `make hooks-status` | Show installed hooks and config |
| `make hooks-logs` | View recent hook logs |
| `make hooks-debug-on` | Enable debug logging |
| `make hooks-debug-off` | Disable debug logging |

### OpenCode Integration

This fork adds support for [OpenCode](https://opencode.ai) as an alternative to Claude Code CLI. The `opencode-plugin/` directory contains a plugin that sends OpenCode lifecycle events to the same backend API.

> **⚠ Breaking in v0.24.0:** a non-localhost `CLAUDE_OFFICE_API_URL` is now clamped to the local default unless `CLAUDE_OFFICE_ALLOW_REMOTE=1` is set (the Claude Code hooks always did this). If your backend runs on another host, set `CLAUDE_OFFICE_ALLOW_REMOTE=1` or events will silently post to localhost.

#### Install

```bash
make opencode-install
```

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

#### Uninstall

```bash
make opencode-uninstall
```

#### OpenCode Plugin Commands

| Command | Description |
|---------|-------------|
| `make opencode-install` | Build and register plugin with OpenCode |
| `make opencode-uninstall` | Remove plugin from OpenCode |
| `make opencode-reinstall` | Uninstall and reinstall plugin |
| `make opencode-build` | Build plugin without registering |

#### Environment Variables

| Variable | Default | Description |
|----------|---------|-------------|
| `CLAUDE_OFFICE_API_URL` | `http://localhost:8000/api/v1/events` | Backend API endpoint. Non-localhost values are reset to the default unless `CLAUDE_OFFICE_ALLOW_REMOTE=1` |
| `CLAUDE_OFFICE_ALLOW_REMOTE` | `0` | Set to `1` to permit a non-localhost backend (hooks + OpenCode plugin; opt-in since payloads carry tool I/O and file paths) |
| `CLAUDE_OFFICE_TIMEOUT_MS` | `1500` | HTTP request timeout |
| `CLAUDE_OFFICE_DEBUG` | `0` | Set to `1` to log events to stderr |

#### Event Mapping

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

| OpenCode Event | Backend Event |
|----------------|---------------|
| `session.created` | `session_start` |
| `session.deleted` | `session_end` |
| `session.idle` | `stop` |
| `session.compacted` | `context_compaction` |
| `chat.message` hook | `user_prompt_submit` |
| `tool.execute.before` | `pre_tool_use` / `subagent_start` |
| `tool.execute.after` | `post_tool_use` / `subagent_stop` |
| `permission.ask` | `permission_request` |
| `step-finish` part | `reporting` (token usage) |
| `message.updated` (assistant) | `reporting` (token usage) |

### Docker Deployment

| Command | Description |
|---------|-------------|
| `make docker-build` | Build Docker image |
| `make docker-up` | Start container in background |
| `make docker-down` | Stop container |
| `make docker-logs` | View container logs |

See [Docker Guide](https://github.com/paulrobello/claude-office/blob/HEAD/docs/guides/deployment.md) for detailed configuration.

### Accessing the Visualizer

Once running, open [http://localhost:3000](http://localhost:3000) in your browser.

## Project Structure

```
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
```

## Troubleshooting

### Hooks Not Firing

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

### Frontend Not Updating

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

### Backend Errors

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

### Common Issues

| Issue | Solution |
|-------|----------|
| "Session already exists" | Run `make dev-tmux-kill` first |
| Port 8000 in use | Stop other services on that port |
| Port 3000 in use | Stop other services on that port |
| Hooks not detected | Restart Claude Code after installing hooks |

## Contributing

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

## Related Documentation

- [Quick Start Guide](https://github.com/paulrobello/claude-office/blob/HEAD/docs/guides/quickstart.md) - Get running in under 5 minutes
- [Architecture](https://github.com/paulrobello/claude-office/blob/HEAD/docs/architecture/ARCHITECTURE.md) - System design, data flow, component details
- [Whiteboard Modes](https://github.com/paulrobello/claude-office/blob/HEAD/docs/reference/whiteboard-modes.md) - 12 display modes with keyboard shortcuts
- [Docker Guide](https://github.com/paulrobello/claude-office/blob/HEAD/docs/guides/deployment.md) - Docker deployment and configuration
- [AI Summary](https://github.com/paulrobello/claude-office/blob/HEAD/docs/reference/ai-summary.md) - AI-powered summary service documentation
- [Backend README](https://github.com/paulrobello/claude-office/blob/HEAD/backend/README.md) - Backend-specific setup
- [Frontend README](https://github.com/paulrobello/claude-office/blob/HEAD/frontend/README.md) - Frontend-specific setup
- [Hooks README](https://github.com/paulrobello/claude-office/blob/HEAD/hooks/README.md) - Hook installation details
- [OpenCode Plugin](https://github.com/paulrobello/claude-office/tree/HEAD/opencode-plugin/) - OpenCode integration plugin
- [Scripts README](https://github.com/paulrobello/claude-office/blob/HEAD/scripts/README.md) - Testing and simulation scripts
- [CLAUDE.md](https://github.com/paulrobello/claude-office/blob/HEAD/CLAUDE.md) - AI assistant instructions for this project

## Star History

[![Star History Chart](https://api.star-history.com/svg?repos=paulrobello/claude-office&type=Date)](https://star-history.com/#paulrobello/claude-office&Date)