terminal-browser:在 Claude Code 浏览器窗格中查看实时网页
用 /browser 在 Claude Code 内的窗格中打开真实的网页浏览器,通过 kitty 图形协议绘制画面。
权限
- 读取文件可以读取你电脑上的文件并列出目录($.fs.read / list / stat / exists)。
- 执行命令可以在你的电脑上运行 shell 程序($.process.run / spawn)。具体运行哪些程序请查看源码。
- 网络访问可以发起 HTTP 请求或与 MCP 服务器通信($.http.fetch / $.mcp.*)。
- 拦截工具调用能看到 Claude 发起的每一次工具调用(tool.call / tool.check),并可以阻止或修改它。
- 修改界面在 Claude Code 界面中绘制内容:横条、面板、状态文字、弹出通知(ui.render / $.ui.*)。
- 添加命令/工具注册新的斜杠命令或工具,供你或 Claude 调用($.command.register / $.tool.register)。
- 实测版本
- v2.1.310
- 最近实测
- 需要
- Claude Code ≥ 2.1.287
- 显示位置
- 面板
在 Claude Code 中安装:
/plugin install terminal-browser --marketplace zenbu-labs/terminal-browser这个插件能做什么?
terminal-browser 由 Zenbu Labs 开发,是一款 Claude Code 浏览器插件:它在 Claude Code 内运行一个真实的网页浏览器。输入 /browser,对话旁边会打开一个窗格,显示一个实时页面。输入 /browser example.com,就会加载该网站。再次运行 /browser 或 /browser close 即可关闭。你可以在窗格中点击、输入和滚动,输入会传给页面。
实际的渲染由一个基于 Chromium 的浏览器完成,它是独立的 terminal-browser 程序的一部分。插件负责启动它,把窗格大小以及你的鼠标和键盘输入发给它,并把它的画面帧作为图像绘制在窗格中。这就是它只能在支持 kitty 图形协议的终端(例如 Ghostty 和 kitty)中工作的原因。
当你和 Claude 一起构建 Web 应用时,这个插件很有用。你可以不离开会话就查看 localhost:3000 上的开发服务器,或阅读一份 HTML 报告。作者把该插件标为实验性,因为它依赖仍在变化中的函数钩子 API。
安装
使用安装区块,它会添加作者的插件市场,并从中安装该插件。你还需要让 terminal-browser 程序位于 PATH 中(见常见问题)。在任何已经打开的会话中,请运行 /reload-plugins。
$ install terminal-browser
需要 Claude Code ≥ 2.1.287
从作者自己的 marketplace 安装: zenbu-labs/terminal-browser
1.在 Claude Code 中一行安装
/plugin install terminal-browser --marketplace zenbu-labs/terminal-browser粘贴到正在运行的会话中(v2.1.275+)。Claude Code 会先询问是否添加该插件市场。
2.从终端安装
claude plugin marketplace add zenbu-labs/terminal-browser claude plugin install terminal-browser@terminal-browser然后在所有已打开的会话中运行 /reload-plugins。
3.免安装试用
git clone https://github.com/zenbu-labs/terminal-browser claude --plugin-dir ./terminal-browser/claude-code-plugin仅在当前会话中加载该插件,不会写入你的设置。
工作原理
会话在终端中启动时,插件会注册一个 /browser 命令。命令处理函数很短,来自 hooks/register.tsx:
on('command.run', { command: 'browser' }, async ($, e) => {
const arg = e.args.trim()
if (arg === 'close' || (!arg && state.open)) {
await closeBrowser($)
return { text: 'Closed terminal-browser' }
}
const opened = await openBrowser($, arg || null)
return { text: opened.ok ? 'Opened terminal-browser' : opened.error }
})浏览器第一次打开时,startBridge 会运行 terminal-browser capabilities,检查已安装的版本是否支持 embedding 和 image-frames。然后它运行 terminal-browser claude-bridge launch,输出一个本地端口和一个随机令牌。此后,所有通信都通过 HTTP 发往该端口上的 127.0.0.1,令牌作为 bearer 头发送:
watchBridge对/state做长轮询,并用$.ui.blit把每一帧新画面复制到窗格中。画面帧来自共享内存,因此 HTTP 响应中不会传输任何图像数据。surface.tsx大约每 20 毫秒收集一次你的按键和鼠标事件,插件把它们 POST 到/input。滚轮事件也走同样的路径。- 窗格大小的变化会 POST 到
/size,第一个 URL 则 POST 到/open。 - 当浏览器有文本要交给代理时,插件从
/inbox/take取出,并用$.prompt.fill放进你的提示框。如果浏览器附带了截图,也会加上它的那一行。在你按下 Enter 之前,什么都不会发送。
只有主机名的输入会变成 https:// URL,localhost 地址则变成 http://。这个辅助函数位于 hooks/urls.ts。
自定义
插件只有一个选项 agentTool,默认关闭。开启后,插件会注册 open 和 close 两个工具,Claude 可以调用它们在窗格中显示页面。可以在 /config 中设置,或按 README 所示写在 ~/.claude/settings.json 的 pluginConfigs 下。
其他插件也可以驱动这个浏览器。该插件向引擎添加了 $.browser.open({ url }) 和 $.browser.close(),并在 hooks/browser.d.ts 中提供类型。借助它们,插件可以添加 /tldraw 或 /open-pr 之类的命令,在窗格中打开页面。
权限与安全
我们读过 claude-code-plugin/ 中提交 2165ae7 的每一个文件,包括 register.tsx、surface.tsx、bridge-protocol.ts、urls.ts 和类型文件。代码是普通的 TypeScript,没有压缩或打包后的代码。
- 运行命令(
$.process.run):只运行terminal-browser程序,参数为capabilities和claude-bridge launch。它们都是 argv 数组,超时分别为 10 秒和 20 秒。在开发检出中,如果存在../cli/dist/main.js,则改为运行node ../cli/dist/main.js。 - 网络(
$.http.fetch):只访问http://127.0.0.1:<port>,即上文启动的本地桥接服务,每次启动使用独立的令牌。README 指出,你的操作系统可能会询问是否允许终端访问本地网络。 - 填充提示框(
$.prompt.fill):浏览器发给代理的文本会被放进输入框,但绝不会自动提交。 - 添加工具(
$.tool.register):只在你开启 agentTool 时才会添加。 - 它不写入文件,不修改设置,也不读取你的对话记录。
浏览器本身是独立的 terminal-browser 程序,通过 curl | bash 脚本安装,不属于这个插件。在同一个仓库中,该程序的代码会向 PostHog 的欧盟端点发送匿名使用事件(启动、日活、升级、崩溃类型)。设置了 DO_NOT_TRACK 或 TERMINAL_BROWSER_NO_TELEMETRY 时,代码会跳过这些事件。此外,和任何浏览器一样,它会加载你打开的任何网站。
- 读取文件
- 可以读取你电脑上的文件并列出目录($.fs.read / list / stat / exists)。
- 执行命令
- 可以在你的电脑上运行 shell 程序($.process.run / spawn)。具体运行哪些程序请查看源码。
- 网络访问
- 可以发起 HTTP 请求或与 MCP 服务器通信($.http.fetch / $.mcp.*)。
- 拦截工具调用
- 能看到 Claude 发起的每一次工具调用(tool.call / tool.check),并可以阻止或修改它。
- 修改界面
- 在 Claude Code 界面中绘制内容:横条、面板、状态文字、弹出通知(ui.render / $.ui.*)。
- 添加命令/工具
- 注册新的斜杠命令或工具,供你或 Claude 调用($.command.register / $.tool.register)。
兼容性与故障排除
我们在 Claude Code 2.1.310 上,对提交 2165ae7 使用 claude plugin validate 验证了该插件。验证通过,并带有一条插件目录警告。该插件没有测试,所以没有运行 claude plugin test。自该提交以来,上游仓库又有了新的提交,但之后的提交都没有改动 claude-code-plugin/,因此我们审查的代码仍是当前的插件。这是标准级页面:没有演示录屏。需要函数钩子,因此你需要 Claude Code 2.1.287 或更高版本。
/browser提示 "Please install terminal-browser first":安装该程序,并确认它在你的PATH中。- 提示需要更新的版本:运行
terminal-browser upgrade。 - 屏幕显示错乱或窗格一直为空:你的终端可能不支持带 unicode 占位符的 kitty 图形协议,或者你正处在 tmux 或其他多路复用器中。
- 鼠标位置略有偏差:README 把它列为已知限制,因为 Claude Code 不会报告像素级的鼠标位置。
- 窗格无法变得更宽:Claude Code 为聊天区域保留了最小宽度。
常见问题
- 除了插件之外,使用这个 Claude Code 浏览器还需要别的东西吗?
- 需要。插件只负责绘制窗格,浏览器本身是 terminal-browser 程序,需要另外安装(curl -fsSL https://terminal-browser.sh/install | bash,或 brew install terminal-browser)。没有它时,/browser 会回复 "Please install terminal-browser first"。如果已安装的版本太旧,它会提示你运行 terminal-browser upgrade。
- 它能在哪些终端里使用?
- 只支持带 unicode 占位符的 kitty 图形协议的终端,例如 Ghostty、kitty,以及基于 libghostty 构建的 cmux 和 supacode。在其他终端中,README 提醒打开浏览器可能会让屏幕显示错乱。tmux 之类的多路复用器目前通常会让它失效。
- Claude 能自己在浏览器中打开页面吗?
- 只有在你打开 agentTool 选项时才可以,该选项默认关闭。它会添加模型可以调用的 open 和 close 工具。不开启时,Claude 仍然可以按 README 所说,使用 terminal-browser CLI 在分屏窗格中打开浏览器。
- 怎样关闭浏览器窗格?
- 运行 /browser close,或者在窗格打开时运行不带参数的 /browser。在 Claude Code 中关闭窗格,也会通知 terminal-browser 浏览器已被关闭。
- 其他插件可以打开这个浏览器吗?
- 可以。插件为其他插件的钩子添加了 $.browser.open({ url }) 和 $.browser.close()。README 展示了用这种方式构建的 /tldraw 命令。
# 相关插件
精选Agent Profiler
看清 Claude Code 会话的时间花在哪:模型等待、工具和子代理,状态栏实时显示,并可导出 OTLP 追踪。
- 状态栏
- 面板
- 弹出通知
- 写入文件
- 网络访问
- 拦截工具调用
- 修改界面
- 添加命令/工具
已在 v2.1.303 实测
精选Agent Radar
在提示词上方为每个运行中的子代理显示一行实时状态:用时、工具数和当前动作,另有 /radar 面板。
- 输入框上方
- 面板
- 弹出通知
- 拦截工具调用
- 读取你的提示词
- 修改界面
- 添加命令/工具
已在 v2.1.291 实测
精选
精选Context Inspector
显示 Claude Code 上下文窗口被什么占满、其中有多少是重复读取和重复输出,以及压缩保留了什么。
- 状态栏
- 面板
- 弹出通知
- 写入文件
- 拦截工具调用
- 读取你的提示词
- 修改界面
- 添加命令/工具
已在 v2.1.303 实测
更多 面板与仪表盘、为 Claude 添加的工具。