term-browser

Browse real web pages from your terminal without leaving your shell workflow. term-browser gives you an interactive page view for quick lookups, local HTML previews, and command-driven navigation from scripts or another terminal pane.

Features

• Web page display in the terminal.
• Keyboard input into page forms.
• Mouse scrolling and clicking.
• Basic TUI controls for navigation, address editing, and quitting.
• CLI control for AI agents and interoperability with Playwright CLI.

Demo

Requirements

• A Chromium or Chrome executable. The browser is discovered from --browser-path, TERM_BROWSER_BROWSER_PATH, CHROME_PATH, PLAYWRIGHT_CHROMIUM_EXECUTABLE_PATH, common system paths, or a local Playwright browser cache.
• For high-resolution terminal rendering with the kitty renderer, use a terminal that supports the kitty image protocol, such as kitty, Ghostty, or WezTerm.

Install

Download a prebuilt binary from the GitHub Releases page, or install from source with Go:

go install github.com/runoshun/term-browser/cmd/term-browser@latest

go install requires Go 1.24.13 or newer.

Usage

term-browser <url-or-html-file> [options]

Useful flags:

• --interval 1: seconds between refreshes. This is the default.
• --frames 3: render a fixed number of frames.
• --cols 100 --rows 30: override terminal size detection.
• --cell auto: query the terminal text area size and derive CSS pixels per terminal cell, falling back to 10x20 if the terminal does not answer. Use --cell 10x20 to force a value.
• --dpr 2: improve page sharpness on HiDPI terminals.
• --profile-dir ~/.local/share/term-browser/profiles/default: use a persistent browser profile for cookies, local storage, and login state across launches. This is the default.
• --browser-path /path/to/chrome: use an explicit Chromium/Chrome executable.
• --cdp-url http://127.0.0.1:9222: use an already running browser instead of launching a new one.
• --browser-launch-options '{"args":["--lang=ja-JP"]}': pass extra Chromium launch flags. args are appended.
• --headful: launch a visible browser window instead of headless mode. This requires a desktop/display environment.
• --renderer auto|kitty|iterm2|block|quadrant|braille: choose output renderer. auto detects kitty/ghostty, including the current tmux client when possible.
• --session tb: name the running browser session for external commands. Defaults to default.
• --no-display: run without drawing the page in the terminal.

Keyboard And Mouse Console

When stdin/stdout are attached to a terminal, the display loop accepts a small keyboard and mouse console:

• Ctrl-c / Ctrl-d: quit from any keyboard mode.
• q: quit in vim mode.
• Header < / >: go back/forward.
• Header ○ / ◉: toggle the virtual mouse overlay.
• Header x: quit.
• Footer mode label: toggle normal/vim keyboard navigation mode.
• Header address bar: click to edit the current address.
• Header near the right edge: loading spinner when the page is still loading.
• Left click in the page: click the page at the terminal cell position.
• Mouse wheel: scroll down/up.
• o: edit the header address bar.
• Normal mode is the default: keys are sent to the page; Esc is sent to the page and enters vim mode.
• i: switch from vim mode back to normal mode.
• m: toggle the virtual mouse overlay. Mouse visibility is independent from normal/vim mode and can be combined with either mode.
• j / k / h / l: scroll down/up/left/right in vim mode.
• g / G: scroll to top/bottom.
• Ctrl-f / Ctrl-b: scroll down/up by half a screen.
• < / >: go back/forward.
• + / - / 0: zoom in/out/reset.
• Enter / Space / Esc / Backspace / Delete: pass the key through to the page.
• r: redraw now.
• R: reload the page.
• ?: show the key summary.

Local HTML files can be opened directly, which is useful for previewing generated pages and small demos from the shell.

External Control

term-browser can be controlled from another terminal or automation tool while it is running. Use this to open a URL from a script, an editor command, or an AI agent without restarting the terminal browser.

term-browser open [--session <name>] <url>
term-browser cdp-url [--session <name>]

Start a session. If --session is omitted, the session name is default:

term-browser https://example.com

Navigate that running tab from another terminal:

term-browser open https://openai.com

Print an attach URL for tools such as playwright-cli:

playwright-cli attach --cdp="$(term-browser cdp-url)"

Named sessions let you keep separate browser targets for different tasks. If --session is omitted, external commands use the default session.

Renderer Support

Renderer	Status	Notes
kitty	Supported	Tested with kitty image protocol terminals.
iterm2	Experimental	Implemented, but not yet manually verified.
block	Supported	ANSI truecolor half-block output.
quadrant	Supported	ANSI quadrant-character output.
braille	Supported	ANSI braille-character output.
sixel	Not supported	Fails early with an explicit error.

When running inside tmux, auto checks the current tmux client's outer terminal name, so kitty and ghostty should select the kitty renderer automatically in normal sessions. tmux still needs passthrough enabled:

set -g allow-passthrough on

For tmux TTY rendering, the kitty renderer uses Unicode placeholders so the image is anchored to the tmux pane instead of the outer terminal cursor. This requires kitty 0.28.0 or newer.

If tmux cannot report the outer terminal, use --renderer kitty explicitly.

License

Apache License 2.0. See LICENSE.