Herdr Browser is deprecated, and its PNG round trip is the reason

The whole experiment was putting a real Chromium view in a terminal pane

Herdr Browser was an experiment in making browser automation visible and interactive inside a Herdr pane, and the repository description puts it plainly: render a real Chromium view inside a Herdr pane and drive it over the Chrome DevTools Protocol.

The rendering path is one line of diagram.

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

Read it as a chain of format conversions rather than as a list of components. Chromium produces frames, CDP's screencast capability hands them over, the frames become PNG images, and those images travel through Herdr's pane graphics stream to the terminal, where something at the far end has to draw them.

The driving side is the other half of the description. CDP is not only a screenshot API, so a project built on it can act on a page rather than only display one, which is what makes the pane interactive rather than a video feed.

The important framing is that the terminal is the display, not the browser. A real Chromium instance did the work, and Herdr carried the result.

Chromium encoded every frame as a PNG and the display path decoded it again

The cost of that design is stated in one sentence in the README, and it is the reason the project ended: this requires Chromium to encode browser frames as PNGs, and requires the display path to decode them again.

That is two lossy-to-lossless transforms per frame, and they happen on the hot path. Encoding a frame is work the browser was not asked to do, decoding it is work the terminal side must do before anything appears, and both scale with frame count rather than with page complexity. A browser that is merely scrolling can saturate the pipeline before it does anything interesting.

The general point is worth separating from this project. Shipping pixels through a pipe means choosing a representation for those pixels, and PNG is a sensible default for the web because a browser tab decodes it anyway. For a terminal pane that receives frames over and over, the encode and decode cycle is pure overhead that the architecture chose and then paid for on every single frame.

The successor project keeps the same CDP idea and changes only that representation.

Terminal Browser writes raw RGBA frames to files and submits metadata instead

The replacement path drops the image codec and adds a compositor stage.

Electron offscreen frame
  → IOSurface (macOS) or shared-memory buffer (Linux)
  → native compositor
  → raw RGBA frame file
  → pane.graphics.stream
  → Herdr → terminal

Electron's offscreen rendering surfaces produce a frame without a visible window. On macOS that frame arrives as an IOSurface, on Linux as a shared-memory buffer, and a native compositor turns it into a raw RGBA frame file.

What crosses the stream is metadata, not pixels.

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

Four fields carry the frame. The format says how to interpret the bytes, the file path says where the raw RGBA frame lives on disk, the sequence numbers the frame so a consumer can order or drop it, and the revision distinguishes a re-send of the same sequence after an edit.

The protocol detail that makes this safe is the acknowledgement. Herdr acknowledges each frame before its buffer can be reused, which is the backpressure that stops a fast producer from filling a frame directory. The README's judgement is that this avoids the PNG encode and decode cycle and gives Terminal Browser a faster foundation for a full browser experience.

That word file-backed is doing real work. The heavy part of a frame now lives in the filesystem, and the pane stream carries a few dozen bytes per frame instead of a compressed image.

The migrate path is a curl command on macOS or Linux, and nothing installs Herdr Browser itself

The README's answer to any question about this repository is to leave it.

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

That script installs Terminal Browser, and the stated platforms are macOS and Linux. The repository then points at the Terminal Browser repository for current usage and documentation, which is the right place to look because this one is frozen.

The absence is worth naming: there is no installation section for Herdr Browser itself. No package to add, no build step to run, no registry name. Everything the README offers is a deprecation warning, two architecture diagrams, one migrate command, and a link.

That shape is common and not necessarily careless. This repository's remaining value is as a record of a failed approach, with the reasoning intact, which is why the diagrams rather than the code are the point. Anyone still holding a dependency on herdr-browser should read the warning before doing anything else, because the rendering path it depends on, CDP screencast to PNG to pane.graphics.stream, is the one being replaced.

bun run browser is the entry point, and the package is marked private at version 0.1.0

What is left in the repository is a small TypeScript project run with Bun.

bun run browser

That maps to src/cli.ts through the browser script. The other scripts cover the pieces of the experiment: plugin:status runs src/actions/status.ts, test-page runs src/testServer.ts, and viewer runs src/viewer.ts. Tests are bun test and the typecheck is tsc --noEmit.

The manifest is small in a way that tells you this was never packaged. The name is herdr-browser, the version is 0.1.0, private is set to true, license is MIT, and the module type is ESM. The only dependencies are devDependencies: typescript at ^5.9.0 and the Bun type definitions at ^1.3.0, with a bun.lock alongside. No runtime dependency on Electron, on a CDP client, or on a PNG library appears there.

The top-level tree matches that shape: .gitignore, LICENSE, README.md, bun.lock, package.json, skills/, src/ and tsconfig.json. A skills directory next to a CLI script suggests the browser behaviour was partly expressed as skills rather than only as code.

private true plus 0.1.0 plus no release tags means there was never a distribution channel for this package. It was a repository you ran from a clone, and it still is, minus the point.

The deprecation notice sits above the architecture, and the licence still permits reuse

The first line of the README is the heading Herdr Browser (Deprecated), followed by a warning block stating that the project is no longer maintained and naming terminal-browser as the replacement. Everything else in the document is written in the present tense about a past tense.

Two facts come from the repository record rather than the text. There are no GitHub releases, so there was never a tagged version to pin against, and the last push was on 2026-08-22.

What that means for a reader depends on what they were planning. If you were going to install Herdr Browser, stop: there is nothing to install and the author has said so. If you were going to read its rendering pipeline to understand how pane graphics work, the diagrams are still accurate as a description of the older, PNG-based path, and they are honest about its cost.

If you are going to reuse code, the licence is MIT, which is permissive enough that the deprecation does not remove the option. It removes the maintenance, not the permission. That distinction is the one to keep straight when you decide whether to port the idea, adopt Terminal Browser, or leave the pane browser idea alone.

The comparison you are left with is the useful part: encoded frames per frame versus raw frames on disk with metadata and acknowledgement. Everything else about a browser in a terminal is downstream of that choice.

Editorial conclusion

Do not adopt Herdr Browser. It is marked no longer maintained in its own README, it publishes no releases, and its last push was on 2026-08-22, so a new dependency on it would be a dependency on archived thinking. If you were evaluating browser-in-a-pane rendering, install Terminal Browser on macOS or Linux with the documented curl command and read its repository instead, because the only thing this repository still teaches is why PNG-per-frame was the wrong shape. Check three things before you port anything: whether the frame acknowledgement step in the current API matches what your code assumes, since Herdr acknowledges each frame before its buffer can be reused, whether your target is macOS or Linux, because the offscreen path differs between IOSurface and shared memory, and that the licence on both sides is MIT before you copy code rather than rewrite it.

Frequently asked questions

Official sources

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