terminal-browser README

The project's README from github.com/zenbu-labs/terminal-browser. As one markdown file: README.md.

terminal-browser

A real browser that runs inside your terminal

Installation

curl (macOS & Linux):

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

Note: Run terminal-browser upgrade to upgrade versions

Homebrew

brew install terminal-browser

Claude code plugin

Install instructions here

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 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:

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 to read pixels generated by chromium directly from the GPU. This 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!)

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.

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 - https://github.com/zenbu-labs/pixel

SSH

The recommended way to use terminal-browser over ssh is running terminal-browser --ssh <ssh arguments>.

The alternative is running terminal-browser directly on the machine you are shh'd into. This will work, but:

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.

Embedded mode

terminal-browser supports embedding inside of existing TUIs. See examples/embedded for a reference implementation

Roadmap

Contributing

To get a local development setup of terminal-browser, the recommended way is to ask a coding agent.

Adding enhanced support for a new terminal

terminal-browser's cli includes sub commands that rely on terminal/multiplexer scripting features. To implement support for a terminal/multiplexer not yet supported, reference existing implementations located here https://github.com/zenbu-labs/terminal-browser/tree/main/terminals/src/terminals

Discord

Acknowledgments

terminal-browser (zenbu-labs/terminal-browser)

Searching Database…

3.9K ·GitHub
Terminal-browser
What is this?A full web browser that runs inside your terminal. It renders real Chromium pixels in the terminal window, so you can browse actual websites right where you run shell commands.
Does it render real websites, or is it text-only like Lynx?Real websites, fully graphical. It draws Chromium's actual pixel output into the terminal via the kitty graphics protocol, and even ships Chrome DevTools (f12 or cmd+shift+i).
Will it work in any terminal?No. Your terminal must support the kitty graphics protocol — ghostty, kitty, cmux, VS Code and many others do.
What can't it do yet?Chrome extensions and design mode haven't shipped — both sit on the roadmap next to the already-done Linux support.
Does it run on Windows?Not per the README: the install targets are macOS and Linux, and Windows is never mentioned in the docs or roadmap.
What can I do with a coding agent in it?Your agent gets full access to interact with any open terminal-browser, which gives it real web capabilities. You can also have it build an HTML plan that opens automatically in a split pane next to the agent, or press ctrl+g to select a page element and send it over.
How does it work over SSH?Prefer 'terminal-browser --ssh': websites run on your local machine while their network requests are proxied through the remote host, so you can open sites living on the remote machine's localhost. Running it directly on the remote box works too, but then every frame and every input event crosses the network.
Can I embed it inside my own TUI application?Yes. Embedded mode is built for dropping the browser into existing TUIs, and the repo ships a reference implementation under examples/embedded.
Can I build my own graphical terminal apps with it?Yes. The machinery behind the browser — a Rust graphics engine whose UI is written in React with a custom renderer, all drawn on one shared canvas — is abstracted into a JavaScript library for building your own graphical terminal applications.
What are similar projects?memex, carbonyl, herdr-web-ui, shipyard, agentbox, zoetrope, zuse, claudecodeui
Which topics is it in?herdr-plugin, chromium, claude-code-plugin, ssh, claude-skills, app, tui, electron, browser, coding-agent, rust, codex
Creator
zenbu-labs
Size
21 MB
Stars
3.9K
Updated
CommitOct 19Releasepixel-v0.2.6Oct 19
Age
3mo
Commits · 90 Days