Skip to content
claudemods

terminal-browser: a real Claude Code browser pane for live web pages

Opens a real web browser in a pane inside Claude Code with /browser, drawn with the kitty graphics protocol.

Permissions

  • Reads filesCan read files and list directories on your machine ($.fs.read / list / stat / exists).
  • Runs commandsCan run shell programs on your machine ($.process.run / spawn). Check the source for exactly which ones.
  • NetworkCan make HTTP requests or talk to MCP servers ($.http.fetch / $.mcp.*).
  • Intercepts tool callsSees every tool call Claude makes (tool.call / tool.check) and could block or change it.
  • Changes the UIDraws into the Claude Code interface: bands, panes, status text, toasts (ui.render / $.ui.*).
  • Adds commands/toolsRegisters new slash commands or tools that you or Claude can invoke ($.command.register / $.tool.register).
tested with
v2.1.310
last tested
requires
Claude Code ≥ 2.1.287
surfaces
pane

Install inside Claude Code:

/plugin install terminal-browser --marketplace zenbu-labs/terminal-browser
All install options ↓

What does this mod do?

terminal-browser, by Zenbu Labs, is a Claude Code browser mod: it runs a real web browser inside Claude Code. Type /browser and a pane opens beside the conversation showing a live page. Type /browser example.com and that site loads. Run /browser again, or /browser close, to close it. You can click, type and scroll in the pane, and the input goes to the page.

A Chromium-based browser, part of the separate terminal-browser program, does the actual rendering. The plugin starts it, sends it the pane size and your mouse and keyboard input, and draws its frames as images in the pane. That is why it only works in terminals that support the kitty graphics protocol, such as Ghostty and kitty.

The plugin is useful when you build a web app with Claude. You can check the dev server at localhost:3000 or read an HTML report without leaving the session. The author marks the plugin as experimental because it relies on the function hooks API, which is still changing.

Install

Use the install block, which adds the author's marketplace and installs the plugin from it. You also need the terminal-browser program on your PATH (see the FAQ). Run /reload-plugins in any session that was already open.

$ install terminal-browser

Requires Claude Code ≥ 2.1.287

Installs from the author's own marketplace: zenbu-labs/terminal-browser

  1. 1.One line, inside Claude Code

    /plugin install terminal-browser --marketplace zenbu-labs/terminal-browser

    Paste into a running session (v2.1.275+). Claude Code asks to add the marketplace first.

  2. 2.From your shell

    claude plugin marketplace add zenbu-labs/terminal-browser
    claude plugin install terminal-browser@terminal-browser

    Then run /reload-plugins in any session that is already open.

  3. 3.Try it without installing

    git clone https://github.com/zenbu-labs/terminal-browser
    claude --plugin-dir ./terminal-browser/claude-code-plugin

    Loads the mod for one session only. Nothing is added to your settings.

How it works

The plugin registers a /browser command when a session starts in the terminal. The command handler is short. It is from 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 }
})

The first time the browser opens, startBridge runs terminal-browser capabilities to check that the installed version supports embedding and image-frames. It then runs terminal-browser claude-bridge launch, which prints a local port and a random token. After that, everything goes over HTTP to 127.0.0.1 on that port, with the token as a bearer header:

  • watchBridge long-polls /state and copies each new frame into the pane with $.ui.blit. The frame comes from shared memory, so no image data passes through the HTTP response.
  • surface.tsx collects your key presses and mouse events, about every 20 ms, and the plugin posts them to /input. Scroll-wheel events go the same way.
  • Pane size changes are posted to /size, and the first URL to /open.
  • When the browser has text for the agent, the plugin takes it from /inbox/take and puts it in your prompt box with $.prompt.fill. If the browser attached a screenshot, its line is added too. Nothing is sent until you press Enter.

Bare host names become https:// URLs and localhost addresses become http://. The helper is in hooks/urls.ts.

Customize it

The plugin has one option, agentTool, which is off by default. When it is on, the plugin registers two tools, open and close. Claude can call them to show a page in the pane. Set it in /config or under pluginConfigs in ~/.claude/settings.json, as the README shows.

Other plugins can drive the browser too. The plugin adds $.browser.open({ url }) and $.browser.close() to the engine and ships the types in hooks/browser.d.ts. With those, a mod can add commands such as /tldraw or /open-pr that open a page in the pane.

Permissions & safety

We read every file in claude-code-plugin/ at commit 2165ae7. These are register.tsx, surface.tsx, bridge-protocol.ts, urls.ts and the type file. The code is plain TypeScript with no minified or bundled code.

  • Runs commands ($.process.run): only the terminal-browser program, with capabilities and claude-bridge launch. These are argv arrays with 10 s and 20 s timeouts. In a development checkout it runs node ../cli/dist/main.js instead, if that file exists.
  • Network ($.http.fetch): only http://127.0.0.1:<port>, the local bridge started above, with a per-launch token. The README notes that your OS may ask whether your terminal can access the local network.
  • Fills the prompt ($.prompt.fill): text the browser sends for the agent is placed in the input box. It is never submitted on its own.
  • Adds tools ($.tool.register): only when you turn on agentTool.
  • It does not write files, change settings or read your transcript.

The browser itself is the separate terminal-browser program. It is installed with a curl | bash script and is not part of this plugin. In the same repository, that program has code that sends anonymous usage events (launch, daily active, upgrade, crash type) to PostHog's EU endpoint. The code skips them when DO_NOT_TRACK or TERMINAL_BROWSER_NO_TELEMETRY is set. The browser also loads whatever sites you open, like any browser.

Reads files
Can read files and list directories on your machine ($.fs.read / list / stat / exists).
Runs commands
Can run shell programs on your machine ($.process.run / spawn). Check the source for exactly which ones.
Network
Can make HTTP requests or talk to MCP servers ($.http.fetch / $.mcp.*).
Intercepts tool calls
Sees every tool call Claude makes (tool.call / tool.check) and could block or change it.
Changes the UI
Draws into the Claude Code interface: bands, panes, status text, toasts (ui.render / $.ui.*).
Adds commands/tools
Registers new slash commands or tools that you or Claude can invoke ($.command.register / $.tool.register).

Compatibility & troubleshooting

We validated the plugin with claude plugin validate on Claude Code 2.1.310 at commit 2165ae7. Validation passed with one plugin directory warning. The plugin has no tests, so claude plugin test was not run. The upstream repository has moved on since that commit, but none of the later commits touch claude-code-plugin/, so the reviewed code is still the current plugin. This is a standard-tier page: no demo recording. Function hooks are required, so you need Claude Code 2.1.287 or later.

  • /browser says "Please install terminal-browser first": install the program and make sure it is on your PATH.
  • It says a newer version is required: run terminal-browser upgrade.
  • The screen garbles or the pane stays empty: your terminal probably lacks kitty graphics with unicode placeholders, or you are inside tmux or another multiplexer.
  • The mouse is slightly off: the README lists this as a known limitation, because Claude Code does not report pixel mouse positions.
  • The pane will not get wider: Claude Code keeps a minimum width for the chat area.

FAQ

Do I need anything besides the plugin to use this Claude Code browser?
Yes. The plugin only draws the pane; the browser itself is the terminal-browser program, which you install separately (curl -fsSL https://terminal-browser.sh/install | bash, or brew install terminal-browser). Without it, /browser answers "Please install terminal-browser first". If the installed version is too old, it asks you to run terminal-browser upgrade.
Which terminals does it work in?
Only terminals that support the kitty graphics protocol with unicode placeholders, such as Ghostty, kitty, and terminals built on libghostty like cmux and supacode. In other terminals the README warns that opening the browser can garble the screen. Multiplexers such as tmux usually break it for now.
Can Claude open pages in the browser by itself?
Only if you turn on the agentTool option, which is off by default. It adds open and close tools the model can call. Without it, Claude can still use the terminal-browser CLI to open the browser in a split pane, as the README notes.
How do I close the browser pane?
Run /browser close, or /browser with no argument while the pane is open. Closing the pane in Claude Code also tells terminal-browser the browser was closed.
Can other mods open the browser?
Yes. The plugin adds $.browser.open({ url }) and $.browser.close() for other plugins' hooks. The README shows a /tldraw command built this way.
>_ diagram-pane

diagram-pane

A side pane that pins the mermaid and ASCII diagrams Claude writes and keeps a live, editable map of the work.

  • pane
  • Writes files
  • Calls the model (uses your quota)
  • Intercepts tool calls
  • Reads your prompts
  • Changes the UI
  • Adds commands/tools
  • Stores data

tested with v2.1.307

>_ glowup

glowup

A side pane for changes, subagents and context, an activity band, JSON packs and themes, and a pixel pet.

  • pane
  • above-prompt
  • spinner
  • status
  • transcript
  • Reads files
  • Writes files
  • Runs commands
  • Network
  • Calls the model (uses your quota)
  • Intercepts tool calls
  • Reads your prompts
  • Changes the UI
  • Adds commands/tools
  • Stores data

tested with v2.1.310

>_ browser-lanes

Browser Lanes

A band above the prompt showing whether your session has a Playwright browser, who is driving it, and who waits.

  • above-prompt
  • toast
  • Reads files
  • Runs commands
  • Intercepts tool calls
  • Changes the UI
  • Adds commands/tools
  • Stores data

tested with v2.1.307

>_ agent-flow

Agent Flow Subagent Tree

A live tree of your Claude Code subagents beside the transcript: status, current tool, approval waits, time and tokens.

  • pane
  • status
  • transcript
  • Intercepts tool calls
  • Changes the UI
  • Adds commands/tools
  • Stores data

tested with v2.1.291

More in Panes & dashboards, Tools you add to Claude.