{"slug": "terminal-browser-setup-guide-standalone-as-a-herdr-plugin-or-hand-it-to-your", "title": "terminal-browser — setup guide: standalone, as a herdr plugin, or hand it to your agent (yoelgal/terminal-browser fork, upstream-proposal branch)", "summary": "A developer released a setup guide for terminal-browser, a fork that renders a real browser inside a terminal pane, offering three installation methods: standalone, as a herdr plugin, or via an agent. The guide includes detailed steps for building from source on macOS arm64 or Linux x64/arm64, with prerequisites such as Node 22, pnpm, and Rust, and emphasizes verification and safety checks.", "body_md": "A real browser drawn inside a terminal pane. Not a screenshot, not a text dump — the actual page, rendered next to your shell, and scriptable from it. You open it with a command, you close it with a command, and it stays where you put it.\n\nThere are three ways to get it. Pick one:\n\n— copy one block into your coding agent.[Let your agent do it](#let-your-agent-do-it)— build, install, run. Nothing else involved.[Just the browser](#just-the-browser)— adds a browser pane type and Ctrl+clickable links.[With herdr](#with-herdr)\n\nPaste this into Claude Code, Cursor, Codex or whatever you use. It is written for the agent, not for you, and it stops rather than guessing when something is missing.\n\n```\nSet up terminal-browser on this machine, from source.\n\nRepo: https://github.com/yoelgal/terminal-browser — branch `upstream-proposal`.\nThis fork publishes no release binaries, so building from source is the only path. There is no\ninstall one-liner for it. Do not look for one.\n\n1. Check the prerequisites and report which are missing. Do not install system packages on your\n   own. Ask me before running any package manager, brew, apt, or sudo command.\n   - Platform: macOS arm64, or Linux x64/arm64. Anything else is unsupported — stop there.\n   - Node 22, pnpm, and a stable Rust toolchain.\n   - macOS: Xcode command line tools (`xcode-select --install`) — a Swift helper is compiled.\n   - Linux: libnss3, libgtk-3-0, libasound2t64, libgbm1.\n   - jq. Only the herdr plugin needs it, but check now so I hear about it once.\n\n2. Build and install the browser:\n     git clone https://github.com/yoelgal/terminal-browser\n     cd terminal-browser\n     git checkout upstream-proposal\n     pnpm install\n     pnpm dist\n   `pnpm dist` builds and installs. App lands in ~/.local/share/terminal-browser/app, shim at\n   ~/.local/bin/terminal-browser.\n\n3. Verify, do not assume: `terminal-browser --version` must print `local-<short sha>`. If it says\n   command not found, ~/.local/bin is missing from PATH — tell me. Do not edit my shell profile.\n\n4. Then check for herdr with `herdr --version`. If there is no herdr, you are done: go to step 6.\n   If there is, take the version and strip any `-preview.<date>-<sha>` suffix, then compare the\n   remaining X.Y.Z against 0.8.2. Anything lower: STOP. Tell me my herdr is too old and that the\n   plugin install would be refused. Do not run `herdr update`, brew, or any other upgrade —\n   upgrading my herdr is my decision, not yours.\n\n5. Only when that base version is 0.8.2 or newer:\n     herdr plugin install yoelgal/terminal-browser/herdr-plugin --ref upstream-proposal -y\n   Step 2 must already be done. The plugin's build step runs UPSTREAM's `curl | bash` installer\n   when it finds no terminal-browser, which would install upstream's build over this fork. With the\n   fork's binary already on PATH that build step does nothing, which is what we want.\n   Verify with `herdr plugin list`: `zenbu-labs.terminal-browser` must be listed.\n\n6. Report back: versions you found, anything missing, whether the plugin went in, anything you\n   skipped and why.\n\nThroughout: do not open a browser window, do not run `terminal-browser open`, `new-tab`, or any\nplugin action, and do not touch my panes, tabs, or focus. Nothing that opens a window or steals\nfocus. Commit nothing and open no pull request. If a step fails, stop and show me the exact output.\n```\n\n**macOS arm64, or Linux x64/arm64.** The installer refuses anything else.**Node 22**,** pnpm**, and a** stable Rust toolchain**— the render engine is a Rust native module.** macOS:**Xcode command line tools,`xcode-select --install`\n\n. A small Swift scroll helper gets compiled.**Linux:**`libnss3 libgtk-3-0 libasound2t64 libgbm1`\n\n. The installer runs`ldd`\n\non the bundled Electron and names anything missing.\n\nA patched Electron is downloaded from the public `zenbu-labs/electron-releases`\n\nmirror during\n`pnpm install`\n\n, and its SHA256 is checked.\n\nThis fork ships no release artifacts, so you build it yourself:\n\n```\ngit clone https://github.com/yoelgal/terminal-browser\ncd terminal-browser\ngit checkout upstream-proposal\npnpm install\npnpm dist\n```\n\n`pnpm dist`\n\nbuilds a release tarball and then hands it to the same installer a published release\nwould use, so you end up in the normal place:\n\n- app at\n`~/.local/share/terminal-browser/app`\n\n- shim at\n`~/.local/bin/terminal-browser`\n\n``` php\nterminal-browser --version      # -> local-66ffc59\nterminal-browser open example.com\n```\n\nThe version is `local-`\n\nplus the short commit you built, so yours changes as the branch moves.\n\nIf your terminal is a VS Code-family editor, run `terminal-browser setup`\n\nonce. Those ship with\nterminal images switched off, and this turns them on.\n\nThat is the whole browser install. If you do not use herdr, skip the next section — nothing below it depends on it.\n\nThe plugin puts the browser under herdr's own controls, so a browser pane behaves like any other pane and links become clickable into it.\n\n```\nherdr plugin install yoelgal/terminal-browser/herdr-plugin --ref upstream-proposal\n```\n\nAdd `-y`\n\nto skip the confirmation prompt. It is required anyway when stdin is not a terminal.\n\nCheck it landed:\n\n``` php\nherdr plugin list               # -> zenbu-labs.terminal-browser (Terminal Browser) enabled\n```\n\nDo the [Just the browser](#just-the-browser) build before this. The plugin has one build step, and\nit exists so the plugin is never installed onto a machine with no browser to drive:\n\n**It does nothing** when`terminal-browser`\n\nis already on your PATH, or`TERMINAL_BROWSER_BIN`\n\npoints at something runnable. Your own build is left alone.**Otherwise it runs upstream's**, which gives you a stock terminal-browser rather than this fork.`curl | bash`\n\ninstaller\n\nSo the ordering is the whole trick: build the fork, then install the plugin, and the plugin drives the fork.\n\nThis is checked and it is a refusal, not a warning. On anything older the install stops before it starts — nothing is checked out, no build step runs:\n\n```\nplugin requires Herdr 0.8.2 or newer; current Herdr is 0.8.0\n```\n\nOnly the `X.Y.Z`\n\npart of your version counts. A preview build like\n`0.8.0-preview.2026-08-17-1147e60bc0a4`\n\ncompares as plain **0.8.0** and is refused however recently\nit was built. Get to 0.8.2 with `herdr update`\n\n, or `brew update && brew upgrade herdr`\n\non a Homebrew\ninstall, then install the plugin.\n\n| Pane type | `browser` , \"Terminal Browser\" — opens as a split |\nAction `open-split` |\nSplits the focused pane and opens a browser to the right |\nAction `open-url` |\nOpens a URL, reusing an existing browser when there is one |\n| Link handler | `^https?://` routes to `open-url` |\n\nFrom a shell inside a herdr pane — the split needs a pane to split:\n\n```\nherdr plugin action list --plugin zenbu-labs.terminal-browser\nherdr plugin action invoke open-split --plugin zenbu-labs.terminal-browser\n```\n\nTwo things will otherwise surprise you:\n\n**A plain click still opens your system browser.** Only Ctrl+click reaches a plugin link handler.**Other plugins win ties.** When more than one enabled plugin claims the same URL pattern, herdr sorts enabled plugins by id and takes the first match.`zenbu-labs.terminal-browser`\n\nsorts near the end of the alphabet, so it yields to most other plugins that want`^https?://`\n\n. If your Ctrl+clicks land somewhere else, that is why — disable the other handler.\n\nA clicked link reuses a browser already open in the same herdr tab first, then one elsewhere in the\nsame workspace. It never reaches into another workspace. With nothing to reuse it splits a new\nbrowser pane. This reuse is a `jq`\n\nquery, so without `jq`\n\ninstalled every click splits a fresh\nbrowser.\n\nIf you are working on terminal-browser itself, you do not have to install over the copy on PATH. Set\n`TERMINAL_BROWSER_BIN`\n\nand every plugin script — pane, split, link reuse — agrees on that binary:\n\n```\nexport TERMINAL_BROWSER_BIN=/path/to/checkout/bin/terminal-browser\n```\n\nPlugin commands inherit the herdr **server's** environment, so export it somewhere the server will\nsee it and restart the server:\n\n```\nherdr server stop && herdr\n```\n\nA value that does not resolve to something runnable is refused by name:\n\n```\nTERMINAL_BROWSER_BIN is set to '…', which is not runnable — fix or unset it\n```\n\nIt does not quietly fall back to PATH. Fix it or unset it.\n\nOpening and moving around:\n\n```\nterminal-browser open localhost:3000\nterminal-browser open ./report.html --split right --size 0.4\nterminal-browser new-tab github.com\nterminal-browser ls                       # running browsers, their profiles, their tab ids\nterminal-browser shutdown                 # all browsers share one process; this stops it\n```\n\nDriving the open page from a script or an agent — everything after `--`\n\nis an agent-browser command:\n\n```\nterminal-browser action -- snapshot\nterminal-browser action -- click @e14\nterminal-browser action -- eval \"document.title\"\n```\n\nSigning in as yourself. This reads cookies out of a Chromium-family profile on this machine — Chrome, Brave, Edge, Arc, Vivaldi and friends; not Firefox or Safari — and copies them into a browser you already have open. It is macOS only and refuses to run elsewhere, because the values are decrypted with a key from your login keychain. Cookies only: no history, no bookmarks, no passwords. In a terminal it shows what it found and asks first.\n\n```\nterminal-browser import-cookies\nterminal-browser import-cookies --domain github.com --from brave\n```\n\nProfiles are separate boxes of cookies and storage, so you can be signed into one site twice:\n\n```\nterminal-browser profile list\nterminal-browser profile create Work\nterminal-browser open github.com --profile work\n```\n\n`terminal-browser: command not found`\n\nafter a clean build.`~/.local/bin`\n\nis not on your PATH:\n\n```\nexport PATH=\"$HOME/.local/bin:$PATH\"\n```\n\n**The page draws as garbage, or not at all, in a VS Code-family terminal.**\nTerminal images are off by default there. `terminal-browser setup`\n\nturns them on.\n\n**Linux: warning: missing system libraries.**\nThe installer checked the bundled Electron and found gaps. Install what it names:\n\n```\nsudo apt-get install libnss3 libgtk-3-0 libasound2t64 libgbm1\n```\n\n**Every Ctrl+click opens a brand-new browser instead of reusing the one on screen.**\n`jq`\n\nis missing. `brew install jq`\n\n, or `apt-get install jq`\n\n.\n\n** plugin requires Herdr 0.8.2 or newer.**\nUpdate herdr. A\n\n`-preview`\n\nsuffix counts for nothing toward the number.** TERMINAL_BROWSER_BIN is set to '…', which is not runnable.**\nA stale override — you moved or rebuilt what it pointed at. Repoint it, or\n\n`unset TERMINAL_BROWSER_BIN`\n\nto go back to PATH. The herdr server keeps the old value until you\nrestart it.**No prebuilt binaries for this fork.** Every install is a build, on every machine.**Do not run** It installs the latest release from the channel your install records, which is upstream's — so it replaces your fork build with upstream's. To move the fork forward, pull the branch and run`terminal-browser upgrade`\n\non a source build.`pnpm dist`\n\nagain.**macOS arm64 and Linux x64/arm64 only.** No Intel macs, no Windows.**Cookie import is macOS only.** On Linux it refuses.", "url": "https://wpnews.pro/news/terminal-browser-setup-guide-standalone-as-a-herdr-plugin-or-hand-it-to-your", "canonical_source": "https://gist.github.com/yoelgal/ada4912b477050e63f00c1f3782137a6", "published_at": "2026-08-22 07:15:16+00:00", "updated_at": "2026-08-22 13:13:42.717405+00:00", "lang": "en", "topics": ["developer-tools"], "entities": ["yoelgal", "terminal-browser", "herdr", "Claude Code", "Cursor", "Codex", "zenbu-labs"], "alternates": {"html": "https://wpnews.pro/news/terminal-browser-setup-guide-standalone-as-a-herdr-plugin-or-hand-it-to-your", "markdown": "https://wpnews.pro/news/terminal-browser-setup-guide-standalone-as-a-herdr-plugin-or-hand-it-to-your.md", "text": "https://wpnews.pro/news/terminal-browser-setup-guide-standalone-as-a-herdr-plugin-or-hand-it-to-your.txt", "jsonld": "https://wpnews.pro/news/terminal-browser-setup-guide-standalone-as-a-herdr-plugin-or-hand-it-to-your.jsonld"}}