agent-theatre

Agent Theatre

像看电影一样观看编码 Agent 工作，而不是看日志。

Agent Theatre 会将 Claude Code 会话变成一个动画场景。你的代码仓库会成为舞台： 文件夹是街区，文件是建筑，测试文件是信标。Agent 是一个角色—— 十二位演员之一——它会走向读取的文件，在编辑的文件上建造，在信标处运行 测试，测试失败时则追逐 bug 小精灵。子 Agent 会作为其他演员从码头抵达。可实时观看，也可 回放任何过去的会话。

二十种舞台。 Agent Theatre 会识别你的代码仓库类型——Web 应用、后端、CLI、数据 项目、游戏、基础设施——并推荐适合的舞台：岛屿、轨道、都市、港湾、天文台、 温室、工坊、街机、王国、前哨、雪原、树冠、泻湖、火山、云顶、珊瑚礁、集市、 修道院、月球基地、灯笼。也可以点击 给我惊喜。

还有一个其他可视化工具都没有、诚实的小细节：如果 Agent 说任务已经完成，但自上次 编辑以来没有任何测试通过，一个小精灵就会躲在它身后。

同一会话，不同舞台，不同主角。选择器会读取你的代码仓库并推荐三个舞台。

六集内置剧集，分别展现不同代码仓库中的不同工作类型——均为合成内容，手工编写，从未录制真实会话：

剧集	类型	内容
登录超时	bug 修复	两个失败的测试、一段宽限时间、一次通过的测试运行——以及证据标签
研究简报	研究	实地笔记、一个数据文件、两次 Web 搜索、一份书面简报；没有声称测试通过
导出端点	新功能	两座新建筑拔地而起，一条路由完成接线，测试套件首次运行即通过
重命名	重构	修改六个文件，一个测试发现疏漏，五十八个测试通过
发布 1.4.0	部署	所有 Shell 操作都在锻造厂完成：构建、计划、超时、重试、部署、打标签
审计	帮手	两位帮手从码头抵达并分头行动，主角则继续工作

可在 agenttheatre.dev 或本地通过 ?demo=research、?demo=feature、?demo=refactor、?demo=deploy、?demo=subagents 观看。

状态

v1.0.0 — 已发布至 npm，包名为 agent-theatre；每次 发布均提供 VS Code 扩展；agenttheatre.dev 上有六集可播放剧集。实时模式（通过钩子）和真实会话回放均已在真实代码仓库中完成端到端验证。设计说明见 docs/design.md。

安装

选择适合你工作方式的选项。它们运行的都是同一个本地舞台；不会有任何内容离开你的设备。

位置	方式	备注
npm（CLI）	npx agent-theatre	Node 22+。使用 npx agent-theatre replay 回放过往会话
Claude Code 插件	/plugin install agent-theatre --marketplace shreyassaw5394/agent-theatre	在 Claude Code 2.1.275+ 上一步完成；会添加钩子、一个 /theatre 命令和一项技能
Homebrew	brew install shreyassaw5394/tap/agent-theatre	tap：shreyassaw5394/homebrew-tap
VS Code	在扩展中搜索 Agent Theatre，或前往市场	命令：打开舞台（实时）、回放会话…、切换文件夹。每个发行版也提供 .vsix
Cursor / Windsurf / VSCodium	从最新发行版获取 agent-theatre.vsix → 扩展 → ⋯ → 从 VSIX 安装…	同一扩展；即将上架 Open VSX
MCP 服务（Cursor、Windsurf、Claude Desktop、Codex、Gemini CLI、VS Code Copilot）	npx agent-theatre init	为你设备上的每个 Agent 注册 agent-theatre serve；--repo 会为团队写入 .mcp.json / .cursor/mcp.json / .vscode/mcp.json。一键安装：
只看演示	agenttheatre.dev	六段合成剧集，无需安装

首次运行（CLI）：

cd your-repo
npx agent-theatre hooks install   # once — skip if you installed the Claude Code plugin, it brings the hooks
npx agent-theatre                 # opens the stage for this repo; run Claude Code in another terminal
npx agent-theatre replay          # pick any past Claude Code session of this repo and watch it
npx agent-theatre hooks uninstall # reverses the install byte-for-byte

标志：--port <n>、--no-open、--set <stage-id>；replay --latest 会跳过选择器。如果你更喜欢全局安装：npm i -g agent-theatre。

**在舞台中：**将鼠标悬停在任意对象上，即可查看它是什么，以及本次会话中发生了什么。实时舞台会在边缘显示 Live，并在你回退查看时显示 Go live 按钮。整个仓库会缩回并显示所有建筑（滚轮可缩放）。全屏（或按 F）只保留舞台和播放控制栏。导出片段会将你看到和听到的内容录制为 mp4/webm，并提供分享面板（下载、系统分享、X、LinkedIn）。当 Agent 需要你时，舞台会提示你并将你引回 Claude Code（在 VS Code 中会聚焦 Claude Code 输入框）；你要在那里回复，而不是在舞台上。当 Agent 暂停工作时，舞台也会提示你：约 20 秒后显示“思考中…”，90 秒后房间灯光变暗、主角坐下、环境音渐弱，并显示统计静默时长的横幅；一有事件到达，所有效果便会恢复。会话结束时，横幅会提示你。舞台会监视启动时所在的文件夹；同时运行的多个舞台（浏览器、VS Code、另一个仓库）都会收到事件。

MCP 工具

agent-theatre serve 是一个 MCP 服务（stdio）。任何 MCP 客户端都可以：

工具	功能
open_stage	启动（或复用）某个文件夹的实时舞台 → URL
list_sessions	列出某个文件夹中过往的 Claude Code 会话：ID、标题、时间
replay_session	打开某个会话的回放（默认最新会话）→ URL
stage_status	事件/节拍数以及最近几种事件类型；绝不包含内容
install_hooks	安装 Claude Code 钩子（使用插件时无需此操作）

在 MCP 注册表中登记为 io.github.shreyassaw5394/agent-theatre。

工作原理

Claude Code ──hooks──▶ agent-theatre (local) ──WebSocket──▶ browser / VS Code webview
     │                        │
     └─ JSONL transcript ─────┘  (replay)

1. 事件。 Hook 载荷（实时）或转录记录（回放）会被标准化为精简、与产品无关的 AgentEvent 架构：read_file、edit_file (+n −m)、run_command (intent)、test_result、subagent_start/stop、waiting_for_user、turn_end，等等。
2. 舞台。 仓库的文件树会变成确定性的布局——六种布局原型之一（环形、网格、条带、散点、梯田、脊柱），根据仓库和舞台选定，因此同一项目在一组场景中可能是环形岛，在另一组中则是梯田脊柱；而在同一组中，布局始终相同。根据相关性，建筑数量上限约为 60 栋；会话触及的每个文件都会被放置。
3. 导演。 事件会变成场景节拍——walk_to、build、run_tests、spawn_gremlin、chase、celebrate、unverified_claim——并带有情绪：好奇、专注、迷茫、开心。
4. 渲染器。 PixiJS、等距视角、柔和光照、全程使用缓动——代码库中不存在匀速补间动画，并且有测试确保这一点。摄像机会对准动作；只有在开场、庆祝和结束时才会展示整个舞台，避免画面杂乱。一个主光源：投下长长的柔和阴影，具有带环境光遮蔽和轮廓光的渐变立面、远处排屋上的空中雾霭、仅作用于灯具和亮着的窗户的泛光，以及在地面上缓缓飘过的云影。 遵循 prefers-reduced-motion 设置。二十种舞台各有独特的轮廓——山墙式港口房屋、宝塔层级、洋葱形穹顶、月球基地舱体、集市帐篷——但都基于相同的几何结构；十二名角色来自同一套程序化生成流程。
5. 声音。 每个节拍都有声音，均通过 Web Audio API 在运行时合成——没有音频文件，也不必担心许可证。每个舞台都有自己的声线（波形、音高、衰减、脚下的表面）和环境音——铺底声、衬垫音，以及偶尔出现的细节音效，例如海鸥、铃声、气泡、风声或集市喧闹声，这些声音会在随机间隔中出现，因此不会循环重复。 音效和背景环境音可分别开关。 你会特别注意到那声「需要你授权」的提示音。

隐私

所有内容都保留在你的设备上。事件流中绝不会包含代码、提示词、命令文本或搜索查询——只包含相对于仓库的路径、计数、命令的首个词和分类后的意图。这是一项经过测试的不变量（packages/core/tests/privacy.test.ts 会在模拟会话中植入秘密，并断言它们不会进入事件流）。

	读取	渲染内容	离开设备
文件路径	是	相对于仓库的路径	从不
文件内容	仅统计（±行数）	否	从不
你的提示词	从不读取尾部内容；从不存储	否	从不
Agent 的结束消息	最后一段，截断至 240 个字符（turn_end.note）	是——显示并附上「轮到你了」，让你知道它询问了什么	从不
命令文本	首个词 + 分类后的意图 + 重定向目标	否	从不
测试输出	仅汇总计数	通过/失败	从不
遥测	—	—	永不收集
音频	—	合成，无文件	从不

服务仅绑定到 127.0.0.1。Hook 会以状态码 0 退出，绝不会阻塞或拖慢你的 Agent。

仓库结构

packages/core（架构、适配器、岛屿、导演——无 DOM，无 fs）· packages/cli · packages/web · packages/vscode · fixtures/（模拟会话）。

社区

有疑问、值得展示的舞台或 v2 创意：Agent Theatre Discord。整个套件（LastSearch、Debug Anything、Agent Theatre）也共用一个服务。

网站

agenttheatre.dev——项目故事、可游玩的 Episode 1、全部二十种舞台、角色阵容、隐私说明和安装须知。agenttheatre.com 会重定向到这里。网站位于此仓库的 site/ 目录，通过 Vercel 从 main 部署；可游玩的演示使用的是 /theatre/ 下的真实 Web 构建包。

许可证

MIT © 2026 Shreyas Sawant 和 Agent Theatre 贡献者。