zenbu-labs/terminal-browser: a Chromium browser drawn into your terminal
A browser inside your terminal
At a glance
- What is it?
- terminal-browser renders real Chromium pixels inside terminals that speak the kitty graphics protocol, and exposes open browsers to coding agents. It is a different animal from Lynx or w3m, and it only runs on macOS and Linux.
- Who is it for?
- Adopt terminal-browser if you already live in ghostty, kitty, cmux or vscode, you are on macOS or Linux, and you want a coding agent to see and drive real web pages in the same tab as your work. Do not adopt it if you need Windows, if your terminal does not implement the kitty graphics protocol, or if you want a lightweight text-mode reader for documentation over a slow link; Lynx and w3m remain the right tools there.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 1 day ago.
- What is it written in?
- Mainly TypeScript, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 18, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
What terminal-browser actually solves
Terminal browsers have historically meant text-mode renderers: Lynx and w3m fetch HTML, discard images and layout, and print a linear approximation of the page. That works for reading documentation and fails for anything interactive. terminal-browser takes the opposite route. It runs Chromium and draws the actual rendered pixels inside your terminal window, so a page looks like the page, not like a transcript of it. The README describes it as "a real browser that runs inside your terminal."
The audience is narrower than "anyone who uses a terminal." The repository lists claude-code-plugin, claude-skills, codex and herdr-plugin among its topics, and the README's use cases are written for people working alongside a coding agent: an agent and a website scoped to the same terminal tab, an agent that can interact with open browsers, or an agent that writes an HTML plan which then opens in a split pane next to it. If you do not run a coding agent in your terminal, the agent-facing half of this tool does nothing for you, and you are left with a Chromium window that happens to be inside a terminal.
How Chromium pixels reach your terminal
The mechanism has three parts, and all three are documented in the README.
First, display. Terminals that implement the kitty graphics protocol, which the README lists as ghostty, kitty, cmux, vscode and "many more," let a program running inside the terminal display pixels. terminal-browser uses Electron's offscreen rendering API to read pixels generated by Chromium directly from the GPU, and pushes them into the terminal through that protocol. The README claims this renders "smoothly without dropping any frames."
Second, input. Once pixels are on screen, the browser still has to receive clicks and keystrokes. terminal-browser listens for mouse clicks, mouse position and keyboard events from the terminal and synthesizes corresponding events for Chromium. Events the terminal cannot report are read from the operating system by "a background swift app to listen for input events (non intrusively)." That background app is what makes trackpad scrolling and infinite-canvas sites work.
Third, the outer UI. The browser chrome is written in React against a custom React renderer, drawn by a graphics engine built on Rust. The README states that the outer UI and the page content share one canvas inside the Rust engine, which is how UI can be layered on top of the page. The same underlying logic has been extracted into a separate JavaScript library, zenbu-labs/pixel, for building graphical terminal applications.
One consequence worth naming: the architecture is macOS and Linux only according to the installation section, and the Swift input listener is a macOS-shaped dependency. The Roadmap lists "linux support" as complete, which suggests it was not always so.
Install and open your first page
On macOS or Linux, the curl installer is the shortest path. The README gives this exact command:
curl -fsSL https://terminal-browser.sh/install | bashHomebrew is the alternative:
brew install terminal-browserUpgrades go through the tool itself rather than your package manager, so after either install path:
terminal-browser upgradeLaunching with no arguments opens the browser. To go straight to a URL, pass it to open:
terminal-browser open <url>You should see the page rendered as pixels inside your terminal, with the browser chrome drawn around it. If you see text or nothing at all, the likely cause is a terminal that does not implement the kitty graphics protocol; that is the dependency the README names first.
Two flags matter early. To place the browser beside your current pane:
terminal-browser --split rightAnd to keep the page running locally while all its network requests leave through a remote machine:
terminal-browser open --ssh <user@host> <url>The README also documents terminal-browser ls for listing open browsers and terminal-browser action, described as "an agent-browser compatible cli for interacting with open terminal-browsers." Keyboard shortcuts are split by platform: quit is ctrl+q or ctrl+c on macOS and ctrl+q on Linux, the command palette is cmd+p on macOS and ctrl+k or alt+k on Linux, and zoom is delegated to your terminal's own zoom keybind rather than handled by the browser.
The SSH mode is the interesting design decision
Running terminal-browser on the machine you are SSH'd into is possible, and the README is explicit that it is the worse option. In that arrangement every frame the website draws must cross the network, and every input event must cross the network before the page can react. The README also notes it misses "extra optimizations" from the kitty graphics protocol's local-client path.
The recommended form, terminal-browser --ssh <ssh arguments>, inverts the data flow: the website runs on your local device, and only the browser's network requests are proxied through the remote machine over SSH. The practical payoff the README states is that you can load any website running on localhost of the remote machine on your local device. That is a genuinely useful property for previewing a dev server on a remote box without port forwarding, and it is the clearest example of the project trading implementation complexity for a workflow that text browsers cannot offer at all.
Note the flag shape: the README's usage line shows --ssh as an argument to open, while the SSH section shows terminal-browser --ssh <ssh arguments> as the recommended invocation. If you script this, read the section rather than the usage block.
Where it breaks, and when Lynx or w3m is the better answer
The hard constraint is the terminal. Without kitty graphics protocol support, there are no pixels, and without pixels there is no product. The README names ghostty, kitty, cmux and vscode as supporting terminals but does not enumerate the full set, so the only reliable test is trying it. A terminal that renders text perfectly well can still be the wrong terminal here.
The second constraint is the platform. Installation is documented for macOS and Linux through curl and Homebrew. Windows is not mentioned in the installation section, and the background input listener is written in Swift. Search interest in a Windows build exists, but the README does not document a Windows install path.
The third is weight. This is Chromium plus an Electron offscreen rendering path plus a Rust graphics engine plus a Swift input helper. That is a large amount of machinery to read a changelog. For documentation over SSH on a constrained connection, or for a machine where you cannot install a browser engine, Lynx and w3m do the job by throwing away the rendering layer entirely. terminal-browser's whole value is that it does not throw it away, which is also its cost.
Finally, development setup. The README says the recommended way to get a local development setup is "to ask a coding agent," and contributing guidance asks that PR descriptions be authored by humans, with motivation clearly defined and PR size minimized. That is an unusual onboarding stance: it assumes the contributor already has an agent workflow.
Lynx, w3m and the text-mode alternative
Lynx and w3m are the honest comparison, because they answer the same question differently. Both parse HTML and render a text approximation: headings, links, form fields and alt text, with no images and no CSS layout. They run anywhere a terminal runs, they are small, and they are fast over slow links. A page that is mostly prose reads fine in them.
terminal-browser makes the opposite trade. It keeps Chromium, so JavaScript executes, CSS applies, and canvas-heavy pages work; the README specifically calls out that websites with infinite canvases work well. The price is the kitty graphics protocol requirement, a macOS or Linux host, and an install that pulls a browser engine. If your page is a dashboard behind a login, Lynx will not help you and terminal-browser will. If your page is a README on a remote server over a hotel connection, the reverse is true. The README also credits awrit as "the first attempt to embed chromium inside a terminal," which is the right place to look if you want to compare embedding approaches rather than text browsers.
Maintenance, licence and upgrade cost
The repository is not archived, and the last push was on 2026-09-17. Releases tracked in the repository include v0.11.1 and v0.11.0 on 2026-09-17 and v0.8.1 on 2026-09-09. The version numbers move in the 0.x range, and the gap between v0.8.1 and v0.11.0 spans eight days, so expect churn rather than a frozen API.
The licence is MIT, which permits commercial and private use and modification provided the copyright notice and permission notice are included. That is a permissive licence, and nothing in the repository suggests additional terms. This is not legal advice; read the LICENSE file in the repository for the operative text.
Upgrade cost is low by design: terminal-browser upgrade is the documented path, and the README notes it for the curl install specifically. Homebrew users have the usual brew upgrade route as well. The real cost is not the upgrade command but the surface area: a Rust graphics engine, a React custom renderer, an Electron offscreen path and a Swift input helper all have to keep working together for the browser to draw anything. The Roadmap lists chrome extensions and design mode as not yet done, so those are gaps rather than regressions. Two contributor-facing details are worth knowing before you file anything: PR descriptions must be human-authored and clearly motivated, and the project asks that PRs be kept small.
Editorial conclusion
Adopt terminal-browser if you already live in ghostty, kitty, cmux or vscode, you are on macOS or Linux, and you want a coding agent to see and drive real web pages in the same tab as your work. Do not adopt it if you need Windows, if your terminal does not implement the kitty graphics protocol, or if you want a lightweight text-mode reader for documentation over a slow link; Lynx and w3m remain the right tools there. Before committing, verify one thing first: that your terminal renders the kitty graphics protocol correctly, because every other feature depends on it. Run terminal-browser open https://example.com and confirm pixels appear before you wire it into an agent workflow.
Frequently asked questions
What is terminal-browser?
It is a browser that runs inside your terminal, using Electron's offscreen rendering API to read Chromium pixels from the GPU and display them through the kitty graphics protocol. The README describes it as "a real browser that runs inside your terminal."
Is there a terminal browser that runs JavaScript?
terminal-browser does, because it embeds Chromium rather than parsing HTML into text. That is the main difference from text-mode browsers such as Lynx and w3m, which render a text approximation and do not execute page scripts.
Can you use terminal as a web browser?
With terminal-browser, yes, provided your terminal implements the kitty graphics protocol. The README names ghostty, kitty, cmux and vscode among the terminals that support it, and without that support the browser cannot draw pixels.
How do I access the browser from the terminal?
Install it with curl or Homebrew, then run terminal-browser to launch it or terminal-browser open <url> to go straight to a page. terminal-browser ls lists the browsers you have open.
What is the best terminal browser?
It depends on what you need. terminal-browser keeps Chromium and draws real pixels, so JavaScript and canvas pages work, but it requires the kitty graphics protocol and macOS or Linux. Lynx and w3m render text only, run almost anywhere, and stay small; pick them when the page is mostly prose.
Community notes