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 (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:
curl -fsSL https://terminal-browser.sh/install | bash
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 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 |
| 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 |
| 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, 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.
We use electrons offscreen rendering API 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!)
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 - 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:
- requires every single frame drawn by the website to be sent over the network
- all user input must be sent over the network before a website can react
- misses out some extra optimizations
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
Telemetry
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.
This is the beginning of the README. Read the rest at the original. Read the full README ↗
