让Claude的一举一动看得见:Vibecraft 3D可视化Claude Code完全入门
让Claude的一举一动看得见:Vibecraft 3D可视化Claude Code完全入门
Vibecraft 是一款用 3D 工坊实时可视化 Claude Code 活动的开源工具。当 Claude 读取文件、编辑代码、执行命令或联网搜索时,你会看到一个角色在 3D 场景的对应工位上忙碌起来——让 Claude Code 的一举一动变得看得见、听得见。
本文带你从零完成 Vibecraft 安装与上手:理解 3D 可视化原理、认识 8 大工位、体验多 Claude 并行(Multi-clauding)与常用快捷键。只需 macOS / Linux + Node.js,几分钟即可跑起来。
Vibecraft 是什么:把 Claude Code 变成一座 3D 工坊
平时用 Claude Code,你只能盯着终端里的文字滚动。而 Vibecraft 把这段过程搬到了一座 3D 工坊(Workshop):
- Claude 每调用一个工具,角色就会走到对应工位上操作
- 工位头顶会悬浮文件路径、命令等上下文标签
- 处理时会显示思考气泡,响应内容同步到右侧活动信息流(Feed)
- 还能发出空间音效——"Claude 在你身后?在你左边?" 都能听出来
一句话概括:你负责用 Claude Code,Vibecraft 负责把它演给你看。 🎬
工作原理:3 步数据流
Vibecraft 由两部分组成,靠 Claude Code 原生 hooks 捕获事件:
| 环节 | 作用 |
|---|---|
| Hooks | 监听 Claude Code 的工具调用 / 会话事件,写成日志并上报 |
| Server | WebSocket 服务器(默认端口 4003),实时广播事件 |
| Browser | Three.js 渲染的 3D 工坊,角色随事件移动 |
Claude Code → Hook 脚本 → WebSocket 服务器 → 浏览器 3D 场景
↓
events.jsonl(持久化日志)
Hook 脚本会把每次事件既写入本地日志、又 POST 给服务器,核心逻辑见 hooks/vibecraft-hook.sh,架构说明可参考 CLAUDE.md。整个过程用的是你本地的 Claude 实例,文件与提示词不会外传。
一键安装步骤(3 步跑起来)
Vibecraft 支持 macOS 与 Linux(Windows 暂不支持,因 hooks 依赖 bash)。前置需要 Node.js 18+、jq 和 tmux。
第 1 步:安装依赖
# macOS
brew install jq tmux
# Ubuntu / Debian
sudo apt install jq tmux
第 2 步:配置 hooks(只需一次)
npx vibecraft setup
它会自动把 hooks 写入 ~/.claude/settings.json,并创建数据目录。执行后需重启 Claude Code 才会生效。
第 3 步:启动服务器
npx vibecraft
打开浏览器访问 http://localhost:4003,然后正常使用 Claude Code 即可。之后每次 Claude 调用工具,你都能在 3D 场景里看到。🚀
💡 想从源码运行:
git clone https://gitcode.com/gh_mirrors/vi/vibecraft,进入目录后执行npm install && npm run dev,前端会在 http://localhost:4002 打开。
8 大工位:一眼看懂 Claude 在干什么
这是 Vibecraft 最有意思的设计——每类工具对应一个专属工位。看到角色走到哪,就知道它在做什么:
| 工位 | 对应工具 | 视觉表现 |
|---|---|---|
| 📚 Bookshelf 书架 | Read |
书架上摆满书 |
| ✏️ Desk 书桌 | Write |
纸张、铅笔、墨水瓶 |
| 🔧 Workbench 工作台 | Edit |
扳手、齿轮、螺栓 |
| 💻 Terminal 终端 | Bash |
发光的屏幕 |
| 🔭 Scanner 扫描仪 | Grep、Glob |
带镜头的望远镜 |
| 📡 Antenna 天线 | WebFetch、WebSearch |
卫星天线 |
| 🌀 Portal 传送门 | Task(子代理) |
发光环形传送门 |
| 📌 Taskboard 任务板 | TodoWrite |
贴满便利贴的看板 |
各工位的 3D 装饰都在 src/scene/stations/ 目录下实现,例如书架的细节构建见 BookshelfStation.ts。子代理(Subagent)会在传送门口"分裂"出迷你 Claude,并行处理任务,非常直观。
多 Claude 并行(Multi-clauding):一人指挥一支 AI 小队
除了观察单个 Claude,Vibecraft 还能同时跑多个 Claude 实例,并统一派发任务:
- 点击 "+ New"(或按
Alt+N)新建一个会话 - 配置名称、目录和启动参数(如
-r、--dangerously-skip-permissions) - 点击某个会话,或按
1-6选中它 - 把提示词发给你想指定的那个 Claude
每个会话都运行在独立的 tmux 中,并实时显示 idle / working / offline 状态。完整的多会话编排 API 见 docs/ORCHESTRATION.md。
常用快捷键速查
| 按键 | 功能 |
|---|---|
Tab / Esc |
在 3D 工坊与信息流之间切换焦点 |
1-6 |
切换会话 |
0 / ` |
显示全部会话 / 总览 |
Alt+N |
新建会话 |
Alt+R |
开关语音输入 |
F |
跟随模式 |
P |
开关工位面板 |
D |
绘制模式(给六边形地砖上色、叠层、加标签) |
常见问题快速排查
遇到问题别慌,对照下表基本都能解决:
| 问题 | 解决办法 |
|---|---|
jq not found |
执行 brew install jq 或 apt install jq |
Agent Not Connected |
确认 npx vibecraft 正在运行,且已执行过 setup |
| 看不到任何事件 | setup 之后重启 Claude Code(hooks 在启动时加载) |
| 连不上 / 端口不对 | 默认端口 4003,检查浏览器地址是否正确 |
🎧 想要更沉浸的体验?Vibecraft 的音效全部由 Tone.js 实时合成,无需任何音频文件,每个工具都有独特音色。完整音效目录见 docs/SOUND.md。
核心文件速览
想深入了解或二开,可以从这些入口入手:
- 服务端:server/index.ts —— WebSocket 与 REST API
- 事件桥接:hooks/vibecraft-hook.sh —— 捕获 Claude Code 事件
- 3D 场景:src/scene/WorkshopScene.ts —— 工坊主场景
- 工位实现:src/scene/stations/
- 安装指南:docs/SETUP.md
- 快速上手:docs/QUICKSTART.md
Vibecraft 让"Claude 正在干什么"这件原本只能靠猜的事,变成了一场看得见、听得见的 3D 演出。装好依赖、跑完 setup,剩下的就交给工坊里的 Claude 吧。🛠️

