1. Claude Office Visualizer 是什么？适用场景

Claude Office Visualizer（下文简称 Office Visualizer）是一个实时像素风“办公室”可视化界面，用来把 Claude Code 的执行过程可视化：

  • “Boss” 角色：主 Claude agent

  • “Employee” 角色：Claude Code 生成/派发的 subagent

  • 通过实时事件流，你可以看到：接收指令、执行任务、工具调用、后台任务、上下文压缩（compaction）等状态变化

典型用途：

  • 直播/录屏展示 Claude Code 的多 agent 工作流

  • 调试：快速感知 agent 是否在工作、是否卡在某一步

  • 团队演示：把抽象的 agent 行为变成“看得见”的进度与节奏

上游项目：https://github.com/paulrobello/claude-office

2. 工作原理（30 秒理解）

Office Visualizer 由三部分组成：

  1. Claude Code：你日常运行的 claude ... 命令

  2. Hooks（钩子）：拦截 Claude Code 过程事件，把事件推送给后端

  3. 后端 + 前端：

  • 后端：FastAPI（默认 :8000）

  • 前端：Next.js + PixiJS（默认 :3000）

  • 后端通过 WebSocket 把状态推送给前端

所以你只要：

  • 装好 hooks

  • 启动后端/前端

  • 运行任意 Claude Code 命令

就能在浏览器看到办公室动画。

3. 安装前准备（Prerequisites）

根据项目说明，建议准备：

  • Python 3.14+

  • Node.js 20+（如果你装了 Bun，会自动检测使用）

  • uv（Python 包管理器）

  • Claude Code CLI 已安装并能正常运行（能执行 claude --version）

  • tmux（可选，但强烈推荐，项目提供 make dev-tmux）

安装 uv（如果没有）：

curl -LsSf https://astral.sh/uv/install.sh | sh

4. 快速开始（最快 5 分钟跑起来）

4.1 拉取代码

git clone https://github.com/paulrobello/claude-office.git
cd claude-office

4.2 一键安装（推荐）

make install-all

这个命令会完成：

  • 后端 Python 依赖安装（uv）

  • 前端依赖安装（bun 或 npm）

  • 安装 Claude Code hooks

4.3 启动开发模式（推荐 tmux）

make dev-tmux

会启动两个服务：

  • 后端：http://localhost:8000

  • 前端：http://localhost:3000

tmux 常用快捷键：

  • Ctrl-b n：下一个窗口

  • Ctrl-b p：上一个窗口

  • Ctrl-b d：detach（服务继续运行）

不使用 tmux：

make dev

5. 验证安装是否成功

5.1 检查后端健康

curl http://localhost:8000/health

期待返回类似：

{"status": "ok"}

5.2 打开前端

浏览器访问：

  • http://localhost:3000

你应该能看到像素风办公室（Boss 工位、空座位、窗口等）。

5.3 跑一条 Claude Code 命令触发可视化

在另一个终端执行：

claude "What is 2 + 2?"

观察：

  • Boss 接收任务（接电话/冒泡）

  • Boss 工作

  • 输出摘要/状态

5.4 验证 subagent 可视化

执行一个更可能触发 subagent 的任务，例如：

claude "Search this codebase for all Python files and summarize what each does"

观察：

  • Boss 分派任务

  • Employee 出现并走到工位

  • 工作完成后返回（如电梯/离场）

6. Hooks 管理（非常关键）

Office Visualizer 是否能“跟着你跑”，关键在 hooks。

常用命令：

make hooks-status
make hooks-logs
make hooks-debug-on
make hooks-debug-off

如果你发现：

  • 页面能打开，但没有任何动画/任务

优先：

  1. make hooks-status 看是否安装成功

  2. make hooks-debug-on 开启 debug

  3. make hooks-logs 或 make hooks-logs-follow 盯日志

  4. 再跑一条 claude ... 看事件是否产生

7. 开启 AI 增强（可选）：自动生成 agent 名称与任务摘要

项目支持“AI-Powered Summaries”（例如用 Claude Haiku 给 agent 取友好名字、生成任务摘要）。

开启方式（来自项目说明）：

  1. 获取 Claude Code OAuth token（需要订阅）：

claude setup-token

  1. 在后端目录创建一个 .env 文件，把 token 写进去：

echo "CLAUDE_CODE_OAUTH_TOKEN=your-token-here" > backend/.env

注意：

  • 不配置 token：可视化仍可用，但会显示原始 agent id、原始工具名/任务名

  • 前端右上角会显示 AI 状态，方便确认是否生效

8. 界面使用要点：白板模式、快捷键、调试

根据项目介绍，Office Visualizer 支持多种 Whiteboard 模式与快捷键：

  • 0-9：切换白板模式（不同版本可能对应不同视图）

  • T：Todo list

  • B：Background tasks

Quick Start 文档提到的浏览器快捷键（部分需在 debug mode 下）：

  • D：切换 debug mode

  • P：显示 agent 行走路径（debug）

  • Q：显示队列槽位（debug）

  • L：显示阶段标签（debug）

  • O：显示障碍物（debug）

  • T：快进城市时间（debug）

9. Docker 部署（后端+前端容器化）

项目支持单容器部署（后端 + 构建后的前端一起跑），但有一个关键前提：

  • hooks 必须仍然在宿主机原生运行

  • 容器需要只读挂载 ~/.claude，用于读取 transcript/token usage 等信息

9.1 准备 .env

cp .env.example .env

配置宿主机 Claude 数据目录（示例）：

# macOS
CLAUDE_PATH_HOST=/Users/yourusername/.claude

# Linux
CLAUDE_PATH_HOST=/home/yourusername/.claude

9.2 启动

docker compose up -d

访问：

  • http://localhost:8000

9.3 为什么要“路径翻译”（Path Translation）

hooks 事件里携带的是宿主机路径（例如 /Users/xxx/.claude/...），容器内看到的是挂载路径（例如 /claude-data/...）。

所以需要：

  • CLAUDE_PATH_HOST：宿主机 .claude 路径

  • CLAUDE_PATH_CONTAINER：容器内挂载点（默认 /claude-data）

这样后端才能把 hooks 上报的路径翻译成容器内可读取的路径。

10. 常见问题排查（Checklist）

10.1 页面正常但没动画

  • 先确认 hooks：make hooks-status

  • 开启 hooks debug：make hooks-debug-on

  • 跟踪日志：make hooks-logs-follow

  • 再跑 claude ... 看是否产生事件

10.2 端口冲突

  • tmux 模式停止：make dev-tmux-kill

  • 或手动清理占用（示例：8000/3000）

10.3 Docker 模式下读不到 Claude 数据

  • 检查 .env 的 CLAUDE_PATH_HOST 是否是“绝对路径”

  • 检查 compose 是否把该目录挂载到 /claude-data（只读）

11. 参考链接

12. 相关文章