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-browserWhat 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.One line, inside Claude Code
/plugin install terminal-browser --marketplace zenbu-labs/terminal-browserPaste into a running session (v2.1.275+). Claude Code asks to add the marketplace first.
2.From your shell
claude plugin marketplace add zenbu-labs/terminal-browser claude plugin install terminal-browser@terminal-browserThen run /reload-plugins in any session that is already open.
3.Try it without installing
git clone https://github.com/zenbu-labs/terminal-browser claude --plugin-dir ./terminal-browser/claude-code-pluginLoads 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:
watchBridgelong-polls/stateand 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.tsxcollects 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/takeand 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 theterminal-browserprogram, withcapabilitiesandclaude-bridge launch. These are argv arrays with 10 s and 20 s timeouts. In a development checkout it runsnode ../cli/dist/main.jsinstead, if that file exists. - Network (
$.http.fetch): onlyhttp://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.
/browsersays "Please install terminal-browser first": install the program and make sure it is on yourPATH.- 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.
# Related mods
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
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
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 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.