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

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

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

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.

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.

App Mode

terminal-browser can be used to build apps in the terminal using browser technology. You can reference terminal-code as a production usage example - https://github.com/zenbu-labs/terminal-code

This is accessible by using the --app-mode option when spawning terminal-browser, and optionally using the preload and main-script options that use electron's preload scripts and main script under the hood.

The following options are the full set of app related options available for terminal-browser open

  --preload=<path>      Run a script inside the context of a web page before it loads (uses electron's preload feature under the hood, runs in an isolated world).
                        terminal-browser specific api's are exposed on globalThis.terminalBrowser
                        {
                          theme: () => { background: [r,g,b], foreground: [r,g,b], ansi: ([r,g,b] | null)[] } | null, // null until the terminal reports its colors
                          onTheme: (cb: (theme: Theme) => void) => () => void, // returns unsubscribe
                          quit: () => void // closes this browser window
                        }
                        --terminal-browser-session=<key> is passed as extra arguments to the renderer process, available via process.argv
  --main-script=<path>  Run a node.js script in the same process as the browser (this is an electron main process)
  --open-tabs-in-popup-stack Links that would open a new tab open a popup over the
                        page instead.
  --allow-clipboard-read
                        Lets websites read from clipboard.
  --no-toolbar          No toolbar or tab strip
  --no-shortcuts        No browser shortcuts, keys go to the page
  --no-context-menu     No right-click menu
  --no-overlays         No toasts or HUDs drawn over the page
  --no-frame            No border or padding, the page fills the pane
  --app-mode            Shorthand for --no-toolbar --no-shortcuts
                        --no-context-menu --no-overlays --no-frame
                        --allow-clipboard-read --open-tabs-in-popup-stack
  --ssh-bundle <dir>    Install and execute a bundle on a remote server. This is useful when paired with
                        --app-mode and --ssh, allowing you to run an application server on a
                        remote machine, then view the output over ssh
  --ssh-bundle-dir <dir>
                        The path --ssh-bundle should be installed to through the ssh server. Defaults to
                        ${XDG_DATA_HOME:-~/.local/share}/terminal-browser/bundles

Roadmap

• linux support ✅
• chrome extensions
• design mode

Contributing

• PR descriptions must be authored by humans and explained well, otherwise we will close them
• When making a PR, the motivation must be clearly defined in the description
• Minimize the size of your PR for the best chance to get it landed

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

• the kitty project for developing the kitty graphics protocol
• awrit - the first attempt to embed chromium inside a terminal