Herdr Browser: a deprecated Chromium-in-a-pane experiment, and what to install instead

What Herdr Browser was trying to fix

Most browser automation is invisible. A script drives a headless Chromium, and the only evidence is a log line or a failure trace. Herdr Browser took the opposite position: the browser should be something you watch happen inside the pane you are already working in. The README frames it as "an experiment in making browser automation visible and interactive inside a Herdr pane", which is a narrow goal with a clear audience. It is for people who live in Herdr, want a Chromium view next to their shell, and are willing to accept an experiment rather than a product. The repository is a Bun and TypeScript project, version 0.1.0, private, MIT licensed, with a src/ directory and a skills/ directory at the top level. It was never published as a package, which matters: there is no npm install path, only the source.

The CDP screencast to PNG pipeline, and why it was replaced

The README states the rendering path plainly:

Chromium → CDP screencast → PNG → pane.graphics.stream → Herdr → terminal

Chromium captures frames, the Chrome DevTools Protocol screencast hands them over, they get encoded as PNG, and those encoded images travel through Herdr's pane graphics stream to the terminal, where the display path decodes them again. That is two conversions per frame, in opposite directions. The README is direct about the consequence: this "requires Chromium to encode browser frames as PNGs and the display path to decode them again". The replacement project, terminal-browser, keeps the same shape but changes the payload. It uses Electron offscreen rendering surfaces and Herdr's newer file-backed frame API, where an offscreen frame becomes an IOSurface on macOS or a shared-memory buffer on Linux, passes through a native compositor, and lands as a raw RGBA frame file in Herdr's frame directory. Instead of image bytes, the pane receives metadata:

{
  "format": "rgba",
  "file": { "path": "..." },
  "sequence": 42,
  "revision": 0
}

The README notes that Herdr acknowledges each frame before its buffer can be reused, which is what makes the file-backed approach safe rather than a race. The trade is real: raw RGBA frames are far larger than a PNG, so the win only exists because Herdr's newer API can reference a file instead of streaming encoded data through the pane. Herdr Browser could not use that API, and no amount of tuning inside its own code would have changed that.

Installing Herdr Browser from source (Bun, no npm package)

There is no install section in the README, and no package on a registry. The project is marked private in package.json, so the only route is the repository itself. The scripts block defines the entry points. To run the browser CLI from a checkout, the repository's own script is:

bun run browser

which maps to bun run src/cli.ts. Two other scripts are worth knowing before you start: the plugin status action and a local test page server.

bun run plugin:status
bun run test-page

Those map to src/actions/status.ts and src/testServer.ts respectively. The test page server is the closest thing to a first real use: start it, point the browser CLI at it, and you have a page to render in the pane without depending on an external site. Type checking is a separate script, bun run typecheck, which runs tsc --noEmit, and the test suite is bun test. Because the README gives no installation steps and no configuration reference, treat the checkout itself as the documentation. The dependency list is only @types/bun and typescript, both devDependencies, so there is no runtime library surface to audit.

The deprecation warning is the first thing in the README

The README begins with a warning block stating that the project is no longer maintained and that readers should use terminal-browser instead. That is not a footnote or a stale banner at the bottom of a long file; it is the opening. The last push to the repository was on 2026-08-22, so the code is not ancient, but the maintainer's own statement overrides any inference you might draw from a recent commit date. The practical failure mode is subtler than a broken build. Herdr Browser depends on Herdr's pane graphics stream and on the CDP screencast path, and the README's own description of the replacement implies that Herdr has since grown a file-backed frame API with per-frame acknowledgement. A plugin built against the older surface can keep working while the host moves on, and when it stops, there is no upgrade path documented here. The README does not document rollback, and it does not describe how to uninstall the plugin from a Herdr configuration. If you are evaluating it because a search result mentioned a Herdr browser plugin, the answer is that the plugin exists as source and is not being carried forward.

Terminal Browser is the named alternative, and the difference is architectural

The README does not hedge about the alternative. It names zenbu-labs/terminal-browser and gives the migration command for macOS and Linux:

curl -fsSL https://terminal-browser.sh/install | bash

The difference is not a rewrite in a different language or a nicer UI. It is where the pixels live between Chromium and the terminal. Herdr Browser sends encoded PNG images through the pane graphics stream and pays for encode and decode on every frame. Terminal Browser renders offscreen with Electron, hands the surface to a native compositor through an IOSurface or a shared-memory buffer, writes raw RGBA to a file in Herdr's frame directory, and submits a small metadata record with a sequence number. Herdr then acknowledges the frame before the buffer is reused. The README's own summary is that this "avoids the PNG encode/decode cycle and gives Terminal Browser a faster foundation for a full browser experience". Note the wording: faster foundation, not faster today. That is an honest claim about headroom rather than a benchmark, and there are no numbers anywhere in the README to check it against. Also note the platform scope: the install command is described for macOS and Linux. The README says nothing about Windows for either project.

Licence and what migration actually costs

Herdr Browser is MIT licensed, and the LICENSE file is at the top level of the repository. That is permissive: you can read the code, copy the CDP screencast approach, and reuse it in your own project with the licence notice intact. It does not give you a maintained plugin, and it does not oblige the author to fix anything. Since the README points to a different repository, the licence question for continued use is really a question about Terminal Browser's terms, which the README does not cover; check that repository's LICENSE rather than assuming the MIT grant travels with the recommendation. On upgrade cost, the honest answer is that there is no upgrade, only a replacement. The two projects do not share a rendering path, so nothing you configure for Herdr Browser carries over to the frame-directory model. The migration is a fresh install plus a fresh read of the new documentation. The one thing the old repository still offers is the CDP screencast pipeline itself, which is a compact reference if you are building something similar and want to see how frames were pulled and encoded.

Editorial conclusion

Herdr Browser should not be adopted for new work. The README opens with a deprecation warning and routes readers to zenbu-labs/terminal-browser, so anyone arriving from a search for the Herdr browser plugin is looking at a frozen experiment, not a maintained tool. If you want a browser inside a Herdr pane, install Terminal Browser on macOS or Linux with the curl command from its README and read that repository's documentation, because the Herdr Browser README documents no rollback and no removal procedure. Read the source under src/ first if you want to know what the old CDP screencast path actually did, and do not expect the migration path to preserve anything: the two projects share a goal, not a codebase.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. ogulcancelik/herdr-browser on GitHub
4. README