A Chromium browser that lives inside your terminal pane.
Watch your localhost render live — without ever leaving tmux.
English · 한국어
A preview, not a full browser. snapweb is for a quick glance at a page without leaving your pane — so a single-monitor trip to the browser and back doesn't break your focus. It's not a full browser replacement.
npx snapweb localhost:3000That's it — your installed Chrome is launched headless and the page is streamed into the pane in real time. Press Ctrl+Q to quit.
First time? Run the environment check first:
npx snapweb doctorInstall it globally with npm i -g snapweb (or as a local dependency) to get the snapweb command — or just run npx snapweb with no install at all.
💡 For sharp text, use a graphics terminal. snapweb paints real images on Ghostty · Kitty · WezTerm · iTerm2. Other terminals — including VS Code's built-in terminal and macOS Terminal.app — fall back to a blocky half-block mode where small text gets hard to read. Run
snapweb doctorto see which mode you're in.
When you develop in the terminal, checking "did the screen come out right?" means switching to a browser window and back, over and over. snapweb renders your page into the next pane instead. Save a file and HMR refreshes it on its own — you keep your eyes where your code is.
- 🖥️ Live preview in a pane — frames are pushed as the page changes, so HMR updates just appear. No window switching.
- 🎨 High fidelity where it counts — real images on Kitty-graphics terminals (Ghostty · Kitty · WezTerm · iTerm2), with a Unicode half-block fallback everywhere else.
- 🖱️ Full interaction — mouse click, drag and scroll plus keyboard input, including Korean/IME text.
- 🔋 Battery-friendly — capture pauses when the pane is hidden, and the defaults favor a low frame rate and CPU throttle for an at-a-glance monitor.
- 🧩 tmux-native — passthrough and focus events are enabled per pane automatically;
doctordiagnoses and prescribes the rest. - 🔍 Zero setup — auto-detects your installed Chrome or Chromium, with nothing extra to download. For Edge, Brave, or another Chromium build, point
--browser(orCHROME_PATH) at it.
- Node.js ≥ 20
- A Chromium-based browser — Chrome or Chromium is auto-detected; for Edge, Brave, or another build, pass
--browser <path>or setCHROME_PATH - For sharp rendering, a Kitty-graphics terminal — Ghostty · Kitty · WezTerm · iTerm2. Other terminals (including VS Code's built-in terminal and macOS Terminal.app) fall back to a blocky half-block mode where small text is hard to read.
snapweb <url> # stream the page
snapweb # stream the default URL from config (if set)
snapweb <url> --once # render a single frame (screenshot) and exit
snapweb config # edit settings in a keyboard UI
snapweb doctor # diagnose the environmentURLs are normalized for you — localhost:3000, example.com, and https://example.com all work.
| Flag | Default | Description |
|---|---|---|
--fps <n> |
10 |
Frame cap while focused (1–90; use 30–60 for smooth motion) |
--scale <n> |
1 |
Stream resolution (2 = Retina-sharp; range 0.5–3) |
--throttle <n> |
4 |
Page CPU throttle (1 = off; range 1–20) |
--renderer <mode> |
auto |
auto | kitty | iterm2 | halfblock |
--cell-aspect <n> |
0.5 |
Cell width/height ratio, used only when pixel query fails |
--browser <path> |
auto | Path to a Chromium binary (also reads CHROME_PATH) |
--once |
— | Render one frame and exit |
--debug |
— | Write diagnostics to ~/.snapweb/debug.log |
For smooth video:
snapweb <url> --fps 30 --scale 2 --throttle 1Run snapweb config for a keyboard-driven settings screen — ↑↓ to move, ←→ to adjust, space to toggle or edit, ⏎ to save, esc to cancel. Settings are written to ~/.config/snapweb/config.json and become the defaults for every run.
Stored settings: default URL, frame rate, scale, page throttle, browser path, and the debug toggle. Once a default URL is set, snapweb with no arguments opens it; passing a URL overrides it for that run.
Precedence is flags > config file > built-in defaults. renderer and cell-aspect are environment-dependent, so they are not stored — they stay on auto-detect and are only set per run via --renderer / --cell-aspect.
| Key | Action |
|---|---|
| Click · scroll · keyboard (incl. Korean) | Forwarded to the page |
Ctrl+Q |
Quit |
Ctrl+L |
Address bar |
Ctrl+R |
Reload |
Alt+← Alt+→ |
Back · Forward (macOS: Option+← Option+→) |
snapweb launches your installed Chromium headless over the DevTools Protocol, streams the page as a screencast, and paints each frame into the pane — as a Kitty/iTerm2 image where supported, or Unicode half-blocks otherwise. The logical viewport stays at a real device size (desktop 1440 / mobile 390, chosen from the pane's pixel aspect ratio) and is uniformly scaled down to fit, so layouts look the way a real browser would render them.
Works out of the box. To make the settings permanent, add to ~/.tmux.conf:
set -g allow-passthrough on
set -g focus-events onIf anything looks off, snapweb doctor will diagnose and prescribe the fix.
snapweb is early and experimental (0.0.x). As a preview tool it favors staying out of your way over pixel-perfect fidelity, so a few rough edges are expected:
- Occasional auto-reload on fast scrolling. Headless Chrome's software renderer can crash under a heavy scroll-plus-capture load; snapweb absorbs that by relaunching Chrome and reconnecting in place — your login survives — which shows up as a brief ~1–3s reload. Capture is throttled adaptively as you scroll faster, to keep it rare.
- Tuned on macOS + tmux + a Kitty-graphics terminal. That's the verified setup; other terminals and Linux should work but are less tested.
- One instance at a time. A persistent Chrome profile keeps you logged in across restarts, so two panes running snapweb at once will conflict over the profile lock.
MIT © JongHwan Baek (Baek'space)