Introducing TermSurf: A Web Browser Inside Your Terminal

Developers live in two windows: a terminal and a browser. Every time you check documentation, inspect a local dev server, or log into a dashboard, you cmd-tab away from your terminal and lose context. TermSurf eliminates that by embedding a full web browser directly inside your terminal panes.

Type web google.com and a real Chromium browser opens right next to your shell. No Electron wrapper. No simplified TUI renderer. A full browser at 60fps with GPU-accelerated rendering.

TermSurf is an Identellica project. It is currently in pre-launch and will have its full launch later this year.

How It Works

TermSurf is built on a protocol-first architecture. Three types of processes communicate over Unix sockets using protobuf:

• TUIs — The web command provides browser chrome (URL bar, status, keybindings) in a terminal UI built with ratatui.
• GUI — Wezboard, a fork of WezTerm, is the terminal emulator that hosts both terminal and browser panes.
• Browser engines — Chromium runs as a separate process per profile, using the Content API directly (not CEF or Electron).

The protocol definition, termsurf.proto, is the most important artifact in the project. GUIs and browser engines are swappable implementations of this protocol. Define once, implement many.

Rendering uses zero-copy GPU compositing via macOS CALayerHost. The Window Server composites the browser directly from GPU VRAM — no per-frame IPC, no texture copies, no bottleneck. The result is native-feeling 60fps browsing at Retina resolution inside terminal panes.

Key Features

Vim-style three-mode keyboard. Control mode keeps terminal keybindings active. Browse mode forwards keyboard and mouse to the browser. Edit mode gives you vim-style URL editing. Switch between them instantly.

Profile isolation. Each browser process serves exactly one profile with its own cookies, sessions, and storage. Run web --profile work and web --profile personal side by side with complete separation.

DevTools in split panes. Open Chromium DevTools directly in a terminal pane with :devtools. Inspect elements without leaving the terminal.

Smart URL resolution. web google.com adds https automatically. web :3000 opens localhost:3000. web ./file.html opens a local file. The URL bar handles the common cases.

Full input support. Mouse clicks, drag, scroll, text selection, and cursor shape changes all work. Cmd+key shortcuts (copy, paste, select all) are forwarded to the browser in browse mode.

The Vision: Multi-Engine, Multi-GUI

Because the protocol is the product, TermSurf is designed to support multiple browser engines and multiple terminal GUIs.

Planned browser engines:

• Roamium (Chromium) — working now
• Surfari (WebKit) — planned
• Waterwolf (Gecko/Firefox) — researched
• Girlbat (Ladybird) — researched

Planned GUI frontends:

• Wezboard (WezTerm fork) — active
• Ghostboard (Ghostty fork) — archived, returning after protocol stabilizes
• Kitty, Alacritty, and iTerm2 support planned

One pane could run Chromium while another runs WebKit. The protocol makes this possible without special-casing each engine.

Current State

TermSurf is pre-launch and macOS only. The core experience works: you can browse the web in terminal panes with full Chromium rendering, multiple profiles, dark mode, DevTools, and vim-style navigation.

What is not yet ready: downloads, file uploads, OAuth flows (target=“_blank” links), JavaScript dialogs, page zoom, and other features you expect from a daily-driver browser. These are all tracked and planned.

The project has 264 documented research issues — an immutable lab notebook recording every experiment, every dead end, and every breakthrough. TermSurf was built using a methodology we call Research Driven Development, where experiments replace plans and documented failures are progress. More on that in a future post.

This is ready for people to look at, explore, and follow along. It is not yet ready for daily use.

What Comes Next

The 1.0 release will target:

• Cross-platform support (Linux and Windows alongside macOS)
• Multiple browser engines beyond Chromium
• Essential web features (downloads, bookmarks, passwords)
• Multi-tab browsing within a single pane
• SSH remote terminal support
• A Neovim plugin (browser.nvim)

The full launch is planned for later this year.

Try It

TermSurf is open source. Visit termsurf.com or explore the codebase on GitHub. Read through the issue history, and build it yourself today. If you are a developer who lives in the terminal and has ever wished the browser was just another pane, TermSurf is being built for you.