Skip to content
Back to search

terminal-browser

MarketplaceWorks with Claude CodeGitHub

A browser inside your terminal

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/zenbu-labs/terminal-browser with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/zenbu-labs/terminal-browser'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/zenbu-labs-terminal-browser/badge.svg)](/listings/zenbu-labs-terminal-browser)

HTML

<a href="/listings/zenbu-labs-terminal-browser"><img src="/api/listings/zenbu-labs-terminal-browser/badge.svg" alt="findsafeskills safety rating" /></a>

Install

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

These steps run a script from the network that findsafeskills does not scan.

curl (macOS & Linux):

curl -fsSL https://terminal-browser.sh/install | bash

> Note: Run `terminal-browser upgrade` to upgrade versions

Homebrew (macOS & Linux):

brew install terminal-browser

Windows

To install on Windows you must be using WSL. Terminals with kitty graphics support are also very limited on Windows, the following are terminals I have tested that terminal-browser will work on inside Windows: - https://noctty.com/

curl -fsSL https://terminal-browser.sh/install | bash

Claude code plugin

[Install instructions here](/claude-code-plugin/README.md)

Usage

terminal-browser # launches the browser
terminal-browser open <url> # opens the browser at a url
terminal-browser --split right # opens the browser in a split pane to the right
terminal-browser open --ssh <user@host> <url> # performs all network requests through a remote server
terminal-browser open --transparent <url> # the terminal background will show through pages without a background color
terminal-browser ls # lists open browsers
terminal-browser action # an agent-browser compatible cli for interacting with open terminal-browsers
terminal-browser upgrade # upgrade to the latest version

Use cases:

- You can have a coding agent and website scoped to the same terminal tab - Your agent has full access to interact with open terminal-browsers, which gives your agent the capability to use the web - You can ask an agent to make HTML plans and then open them inside terminal-browser, which will automatically open in a split pane next to your agent - terminal-browser works over SSH, which allows you to preview websites running on remote machines easily

Shortcuts

| Action | macOS | Linux | | --- | --- | --- | | Quit | ctrl+q or ctrl+c | ctrl+q | | New tab | cmd+t | ctrl+t | | Edit URL | cmd+l | ctrl+l | | Command palette | cmd+p | ctrl+k or alt+k | | Find in page | cmd+shift+f | ctrl+shift+f | | Next / previous match | enter / shift+enter | enter / shift+enter | | Reload | cmd+r | ctrl+r | | Back / forward | cmd+[ / cmd+] or ctrl+[ / ctrl+] | ctrl+[ / ctrl+] | | Zoom in / out / reset | your terminal's zoom keybind | your terminal's zoom keybind | | Devtools | cmd+shift+i or f12 | ctrl+shift+i or f12 | | Devtools console | cmd+alt+j | ctrl+alt+j | | Copy / paste / cut | cmd+c / cmd+v / cmd+x | ctrl+c / ctrl+v / ctrl+x | | Record page (start/stop) | ctrl+r | ctrl+shift+r | | Complete recording review | ctrl+enter | ctrl+enter | | Start element selection (send to agent) | ctrl+g | ctrl+g | | Close popup / overlay | escape | escape |

How does it work?

Terminals that support the kitty graphics protocol, including ghostty, kitty, cmux, vscode and many more, allow a program running in a terminal to display pixels in your terminal. We use this capability to display pixels generated by chromium.

We use [electrons offscreen rendering API](https://www.electronjs.org/docs/latest/tutorial/offscreen-rendering) to read pixels generated by chromium directly from the GPU. Any time a website visually changes, terminal-browser only sends small patches to the terminal that cover changed regions. These choices allows terminal-browser to render smoothly without dropping any frames.

After the browser engine starts and is displaying pixels in the terminal, it needs to be able to read user input for websites to actually work. terminal-browser listens to mouse clicks, mouse position, and keyboard events from the terminal, and then sends synthetic events to chromium based on that data. For any user input events that are not retrievable from the terminal, we read directly from the operating system using a background swift app to listen for input events (non intrusively). This is what allows terminal-browser to implement smooth scrolling, and listen to trackpad events (websites with infinite canvases work great inside terminal-browser!)

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 15 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. {
  2. "name": "terminal-browser",
  3. "owner": { "name": "zenbu-labs" },
  4. "metadata": { "description": "terminal-browser plugins for Claude Code" },
  5. "plugins": [
  6. {
  7. "name": "terminal-browser",
  8. "source": "./claude-code-plugin",
  9. "description": "A browser running directly inside claude code. Preview websites, view HTML documents, and let your agent control the built in browser.",
  10. "homepage": "https://github.com/zenbu-labs/terminal-browser",
  11. "repository": "https://github.com/zenbu-labs/terminal-browser",
  12. "license": "MIT"
  13. }
  14. ]
  15. }
README.md · README · 201 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # terminal-browser
  2. A real browser that runs inside your terminal
  3. <video src="https://github.com/user-attachments/assets/abe2f43e-fc50-4866-b753-33388967945d" controls></video>
  4. ## Installation
  5. ### curl (macOS & Linux):
  6. ```bash
  7. curl -fsSL https://terminal-browser.sh/install | bash
  8. ```
  9. > Note: Run `terminal-browser upgrade` to upgrade versions
  10. ### Homebrew (macOS & Linux):
  11. ```
  12. brew install terminal-browser
  13. ```
  14. ### Windows
  15. To install on Windows you must be using WSL. Terminals with kitty graphics support are also very limited on Windows, the following are terminals I have tested that terminal-browser will work on inside Windows:
  16. - https://noctty.com/
  17. ```bash
  18. curl -fsSL https://terminal-browser.sh/install | bash
  19. ```
  20. ### Claude code plugin
  21. [Install instructions here](/claude-code-plugin/README.md)
  22. ### Usage
  23. ```
  24. terminal-browser # launches the browser
  25. terminal-browser open <url> # opens the browser at a url
  26. terminal-browser --split right # opens the browser in a split pane to the right
  27. terminal-browser open --ssh <user@host> <url> # performs all network requests through a remote server
  28. terminal-browser open --transparent <url> # the terminal background will show through pages without a background color
  29. terminal-browser ls # lists open browsers
  30. terminal-browser action # an agent-browser compatible cli for interacting with open terminal-browsers
  31. terminal-browser upgrade # upgrade to the latest version
  32. ```
  33. ### Use cases:
  34. - You can have a coding agent and website scoped to the same terminal tab
  35. - Your agent has full access to interact with open terminal-browsers, which gives your agent the capability to use the web
  36. - You can ask an agent to make HTML plans and then open them inside terminal-browser, which will automatically open in a split pane next to your agent
  37. - terminal-browser works over SSH, which allows you to preview websites running on remote machines easily
  38. ### Shortcuts
  39. | Action | macOS | Linux |
  40. | --- | --- | --- |
  41. | Quit | ctrl+q or ctrl+c | ctrl+q |
  42. | New tab | cmd+t | ctrl+t |
  43. | Next / previous tab | ctrl+tab / ctrl+shift+tab or cmd+alt+right / cmd+alt+left | ctrl+tab / ctrl+shift+tab or ctrl+pagedown / ctrl+pageup |
  44. | Edit URL | cmd+l | ctrl+l |
  45. | Command palette | cmd+p | ctrl+k or alt+k |
  46. | Find in page | cmd+shift+f | ctrl+shift+f |
  47. | Next / previous match | enter / shift+enter | enter / shift+enter |
  48. | Reload | cmd+r | ctrl+r |
  49. | Back / forward | cmd+[ / cmd+] or ctrl+[ / ctrl+] | ctrl+[ / ctrl+] |
  50. | Zoom in / out / reset | your terminal's zoom keybind | your terminal's zoom keybind |
  51. | Devtools | cmd+shift+i or f12 | ctrl+shift+i or f12 |
  52. | Devtools console | cmd+alt+j | ctrl+alt+j |
  53. | Copy / paste / cut | cmd+c / cmd+v / cmd+x | ctrl+c / ctrl+v / ctrl+x |
  54. | Record page (start/stop) | ctrl+r | ctrl+shift+r |
  55. | Complete recording review | ctrl+enter | ctrl+enter |
  56. | Start element selection (send to agent) | ctrl+g | ctrl+g |
  57. | Close popup / overlay | escape | escape |
  58. ### How does it work?
  59. Terminals that support the kitty graphics protocol, including ghostty, kitty, iTerm2, cmux, vscode and many more, allow a program running in a terminal to display pixels in your terminal. We use this capability to display pixels generated by chromium.
  60. We use [electrons offscreen rendering API](https://www.electronjs.org/docs/latest/tutorial/offscreen-rendering) to read pixels generated by chromium directly from the GPU. Any time a website visually changes, terminal-browser only sends small patches to the terminal that cover changed regions. These choices allows terminal-browser to render smoothly without dropping any frames.
  61. After the browser engine starts and is displaying pixels in the terminal, it needs to be able to read user input for websites to actually work. terminal-browser listens to mouse clicks, mouse position, and keyboard events from the terminal, and then sends synthetic events to chromium based on that data. For any user input events that are not retrievable from the terminal, we read directly from the operating system using a background swift app to listen for input events (non intrusively). This is what allows terminal-browser to implement smooth scrolling, and listen to trackpad events (websites with infinite canvases work great inside terminal-browser!)
  62. The outer UI of the browser is implemented using a graphics engine built on top of rust. The actual UI is defined inside react with a custom react renderer, which allows us to build the UI for the browser using typescript. The UI of the outer browser and the browser content itself is all drawn to the same shared canvas inside the rust engine, which allows us to layer UI on top of the browser.
  63. The underlying logic described here has been abstracted into a javascript library that you can use to build your own graphical applications in the terminal - [`pixel`](./pixel)
  64. ### SSH
  65. The recommended way to use terminal-browser over ssh is running `terminal-browser --ssh <ssh arguments>`.
  66. The alternative is running terminal-browser directly on the machine you are shh'd into. This will work, but:
  67. - requires every single frame drawn by the website to be sent over the network
  68. - all user input must be sent over the network before a website can react
  69. - misses out some [extra optimizations](https://sw.kovidgoyal.net/kitty/graphics-protocol/#local-client)
  70. `terminal-browser --ssh` improves on this by running the website on your local device, and simply proxying all network requests made by the browser via the remote machine over ssh. This means you can load any website running on `localhost` of the remote machine on your local device.
  71. ### Embedded mode
  72. terminal-browser supports embedding inside of existing TUIs. See
  73. [examples/embedded](examples/embedded/) for a reference implementation
  74. ### Telemetry
  75. terminal-browser collects psuedo-anonymous usage events that gives me the ability to see how many people are using the project, which is extremely helpful information for improving the project.
  76. telemetry can be disabled by any of the following:
  77. - DO_NOT_TRACK=1
  78. - TERMINAL_BROWSER_NO_TELEMETRY=1
  79. - disabling via the settings GUI in general
  80. - terminal-browser config set telemetry.usage off
  81. All data that is sent is appended to `~/.local/state/terminal-browser-*/logs/telemetry.jsonl`, which allows you to audit no sensitive or identifying information is leaving your machine.
  82. terminal-browser also collects crash reports if terminal-browser fails to start or unexpected errors occur internally. This can be disabled by any of the following:
  83. - DO_NOT_TRACK=1
  84. - TERMINAL_BROWSER_NO_TELEMETRY=1
  85. - disabling via the settings GUI in general
  86. - terminal-browser config set telemetry.crashReports off
  87. If you are using [pixel/](pixel/), no telemetry is ever active and there is nothing to disable.
  88. ### Roadmap
  89. - linux support ✅
  90. - design mode ⏳
  91. - chrome extensions ⏳
  92. ### Contributing
  93. - PR **descriptions** must be authored by humans and explained well, otherwise we will close them
  94. - When making a PR, the motivation must be clearly defined in the description
  95. - Minimize the size of your PR for the best chance to get it landed
  96. To get a local development setup of terminal-browser, the recommended way is to ask a coding agent.
  97. ### Terminal support
  98. terminal-browser exposes an API that terminals can implement which will allow terminal-browser to reliably script the terminal it is running inside. This allows terminal-browser to open new panes, split panes, send text to a coding agent, and focus panes. Terminals that implement this API can be used to run terminal-browser in a more integrated way.
  99. #### Implementing the API in your terminal
  100. A terminal implements the API by listening on a unix socket and telling terminal-browser where it is:
  101. 1. On launch, listen on a unix socket (for example `$TMPDIR/<your-app-id>.terminal-browser.sock`). Only accept connections from the same user.
  102. 2. Set `TERMINAL_BROWSER_TERMINAL_SOCKET=<socket path>` in the environment of every shell you spawn.
  103. 3. Handle requests. Whenever terminal-browser needs something from the terminal it connects to your socket, writes a JSON request terminated by a newline, and waits for a JSON reply terminated by a newline. Once you have written the reply, close the connection. Every request gets its own connection, so there is no session state to keep.
  104. A request is a JSON object with the method to run, its params, and who is asking. `caller` is the process that ran terminal-browser:
  105. ```json
  106. { "id": "<unique string>", "method": "<name>", "params": { ... }, "caller": { "pid": 12345, "cwd": "/path" } }
  107. ```
  108. Reply with the same `id` and either a `result` or an `error`:
  109. ```json
  110. { "id": "<same id>", "result": { ... } }
  111. { "id": "<same id>", "error": { "message": "..." } }
  112. ```
  113. The first request is always `hello`. Your reply lists which methods you implement, and terminal-browser disables any feature that depends on a method you leave out:
  114. ```json
  115. → { "method": "hello", "params": { "protocol": 1 } }
  116. ← { "result": { "name": "my-terminal", "methods": ["getCurrentPane", "split", "listPanes", "neighbor", "sendText", "pasteKey", "focusPane"] } }
  117. ```
  118. A pane is `{ "id": string, "tab": string }`. `id` is any stable identifier for the pane, `tab` is shared by every pane that is visible on screen together
  119. API:
  120. | method | params | result | powers |
  121. | --- | --- | --- | --- |
  122. | `getCurrentPane` | `{ tty, cwd }` | `{ pane }` or `{ pane: null }` | `ls`, `new-tab`, picking where `--split` goes |
  123. | `split` | `{ from: pane, direction, command: string[], size, tty }` | `{}` | `--split` |
  124. | `listPanes` | `{ tty }` | `{ panes: [{ id, tab, tty, command }] }` | finding the coding agent's pane |
  125. | `neighbor` | `{ from: pane, direction }` | `{ pane }` or `{ pane: null }` | opening next to an existing browser |
  126. | `sendText` | `{ pane, text }` | `{}` | sending page content to a coding agent |
  127. | `pasteKey` | `{ pane }` | `{}` | sending images to a coding agent |
  128. | `focusPane` | `{ pane }` | `{}` | jumping between the browser and the agent |
  129. Extra notes:
  130. - `direction` is one of `right`, `left`, `down`, `up`. `size` is the fraction of the space the new pane should take (`0.4`) or `null` for your default.
  131. - `split` should run `command` (an argv array, quote it for the shell yourself) in the new pane, in the caller's `cwd`.
  132. - `getCurrentPane` receives the caller's `tty`, but the caller may be under a nested pty (a multiplexer, a coding agent wrapper) that no pane owns. When no pane matches the tty, walk the ancestors of `caller.pid` and return the pane whose tty appears first in that chain.
  133. - `listPanes` entries carry the pane's `tty` and the command line of its foreground process, or `null` when unknown.
  134. - `pasteKey` must deliver a literal ctrl+v keypress (byte `0x16`), not a bracketed paste, so a coding agent treats it as a key and reads the clipboard.
  135. The client side, including the exact schema terminal-browser accepts for every result, is [shared/src/terminal-socket.ts](shared/src/terminal-socket.ts). A minimal terminal written in node that answers every method is the `fakeTerminal` in [shared/test/terminal-socket.test.js](shared/test/terminal-socket.test.js), which is a good starting point.
  136. #### Built in support
  137. If a terminal does not implement this API itself, terminal-browser ships built in implementations located in [pixel/packages/pixel/src/terminal/terminals](pixel/packages/pixel/src/terminal/terminals) for: ghostty, kitty, iTerm2, wezterm, cmux, tmux, vscode, tty7, herdr, and supacode. These implement the same operations as the socket methods above as the `Terminal` interface in [pixel/packages/pixel/src/terminal/terminal.ts](pixel/packages/pixel/src/terminal/terminal.ts), using each terminal's own scripting cli. To add support for another terminal or multiplexer, add a file there that implements `Terminal` and register it in `terminals/index.ts`.
  138. ### [Discord](https://discord.gg/t3jzHHfc6z)
  139. ### Acknowledgments
  140. - the [kitty](https://github.com/kovidgoyal/kitty) project for developing the kitty graphics protocol
  141. - [awrit](https://github.com/chase/awrit) - the first attempt to embed chromium inside a terminal

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.