The Problem

Web development and agent workflows split attention between a browser, a terminal, and an editor. terminal-browser collapses that by rendering a real Chromium instance—pixels, input, and all—inside the terminal itself, so a coding agent and a live website share one tab.

What This Does

The project is a collection of six self-contained components. The core is engine/, a Rust graphics engine (pixel-core) with a custom React renderer (pixel-react) that draws the browser UI—tabs, chrome, devtools—onto the same canvas as the page content. The browser/ package wires Chromium's offscreen rendering API to that canvas and translates terminal mouse/keyboard events into synthetic browser input. A cli/ package handles launching, listing, and scripting open browser instances, and a store/ package tracks them.

The README is explicit about the mechanism: terminals supporting the Kitty graphics protocol (ghostty, kitty, VS Code) display the pixels. A background Swift helper captures trackpad events the terminal can't report, enabling smooth scrolling and canvas-style interactions.

How It Is Wired

Execution starts in cli/src/main.ts, which routes to browser/src/daemon.ts to spawn the browser process. The Rust engine's entry point is engine/crates/pixel-core/src/lib.rs, with the React UI mounting through engine/packages/pixel-react/src/index. The internal call graph shows 2,127 resolved edges, with tree_of and font called from 48 places each—they are the widest blast radius. engine/crates/pixel-core/src/tree/mod.rs is the hub: 120 functions called from 24 other files.

The measured paths that leave the process are short: main -> pump -> handle_mouse -> open_menu hits the filesystem via self.menu.open, and load_font -> parse -> parse_markdown reads files via b.open. That means user interaction reaches disk in two hops. The engine/crates/pixel-core/src/terminal.rs file owns terminal I/O (122 functions, reads/writes files), and image_cache.rs owns image decoding.

The import graph shows a cycle in the devtools modules (engine/packages/pixel-react/src/devtools/app.tsx participates in a circular dependency). That costs you on any change there—you can't reason about one module in isolation.

How To Use It

Setup: The README documents a one-liner installer, but for development the recommended path is to ask a coding agent. The repo has package.json files in browser/, cli/, and engine/examples/agent/, plus a Cargo.toml workspace, so npm install and cargo build are the implied build steps.

Running it:

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 ls # lists open browsers
terminal-browser action # an agent-browser compatible cli for interacting with open terminal-browsers

Real-World Use

A coding agent scoped to a terminal tab can open a URL, inspect the rendered page, and iterate on HTML plans that render in a split pane next to it. Because it works over SSH, you can preview a website running on a remote machine without a local browser.

Code Health & Issues

Static analysis found 49 findings (18 high, 31 medium). The high-severity items cluster in the Rust engine: 12 oversized files including engine/crates/pixel-core/src/terminal.rs (615 lines), 25 instances of deep nesting (max depth 10 in engine/crates/pixel-core/src/engine/doc.rs), and 63 duplicated 6-line blocks across 28 files. The devtools import cycle is the other high finding.

SDLC observations: no LICENSE file (all rights reserved by default—a real problem for reuse), no test suite despite 132 source files, and no dependency update bot configured. CI exists via GitHub Actions but lacks a dependency vulnerability scan and sets no job timeouts.

The Bottom Line

This is a technically ambitious project—a real browser in a terminal with a custom React renderer and a Rust graphics engine is non-trivial—and the architecture is coherent. The lack of tests and a license are the two things that would stop me from adopting it in a production workflow. Use it for agent-driven web interaction and remote previews; contribute only if you're comfortable working in a codebase that's still maturing.