Herdr has released native app

Herdr is a desktop app for terminals and coding agents. Keep work in spaces, see which agents need you, and leave terminals running when you close the window.

Install

Linux and macOS

Linux needs a desktop session and a working Vulkan driver. macOS builds are available for Apple Silicon; Intel Mac users can build from source. Linux builds are x86-64 and ARM64.

The installer adds Herdr to your apps and puts the command in ~/.local/bin. Add that folder to your PATH if the installer asks. On macOS the app lives in ~/Applications/Herdr.app. For drag-and-drop installation on Apple Silicon, download Herdr.dmg and drag Herdr to Applications.

Windows

Herdr appears in the Start menu. The installer adds %LOCALAPPDATA%\Programs\herdr-app to your user PATH. Open a new terminal to pick it up.

Both installers download and run code. Read the shell installer or PowerShell installer first if you prefer. They also install herdr-core if it is missing. The app can help install or update a core it cannot use.

Find your work

A space holds work on one machine, usually in one repo. Each space has tabs. Split a tab into panes to put terminals or mod panels beside each other.

An unnamed space follows its first terminal's folder. Name a space or tab when you want a label that stays. New tabs start in the focused terminal's folder.

• Working: still busy.

• Idle: not working, or a finished agent you have looked at.

Click an agent to see it. A worker without a pane opens in peek, over your tab. Keep it as a tab if you want it beside your other work. Ctrl-click a live terminal address in terminal text to peek at it; use Cmd-click on macOS. An address such as t7 means a terminal on the same machine as the terminal showing it. vps/t7 names one on another machine.

The window arranges terminals. The core runs them. Closing the window leaves them running; closing a pane or tab ends its terminals. After a reboot or core crash, kept panes get fresh shells in their last folders, not their old programs.

Work on another machine

Add an SSH machine from Settings → Machines or the sidebar's Add machine action. Pick a host from your SSH config or type how SSH reaches it. Spaces on that machine run their terminals there, not on your computer.

Each machine keeps its spaces, tabs and splits in its core. Connected screens share that structure and the live terminals, but keep their own focus and zoom. Remote work keeps running when your local window closes or your laptop sleeps, as long as the remote machine and core stay up.

Make it yours

Open the command palette to find an action by name, or open Settings to change fonts, colors, sounds and other preferences. The built-in layouts include Herdr, Terminals and Herdr 98. A layout arranges the window. Mods are small JavaScript programs that draw its panels, menus and dialogs.

Duplicate a shipped layout or mod before changing its structure or code. Your copies stay yours; Herdr updates the shipped ones on start. Save a personal layout, mod or key file and the window reloads it. A broken edit keeps the last good version and reports the error.

Ctrl+Shift+P shows every command and its key (Cmd+Shift+P on macOS). Change any key in keys.json; see the keys section of the mod guide for the format.

Updates and privacy

Installed releases check for updates in the background and download a new app beside the running one. It takes over when you quit and reopen, or choose the update action. Your terminals keep running in the core. Settings → Updates shows what is available. What's New opens after an update; you can open it again from the command palette. Builds from source do not update themselves.

Usage telemetry is on by default in releases. Turn it off in Settings → Privacy. Mods are trusted code, not sandboxed extensions. Read security and privacy before installing someone else's mod.

For agents

This prints the agent guide for driving the window. The herdr-core skill points agents here. Use herdr-core for running and coordinating programs; use the app to change what you see.

Build from source

For bugs, mod API requests and code contributions, see Contributing.

Clone this repo with its submodules. Use Rust 1.95.0 and Zig 0.16.0, the versions used in CI. Linux needs the development packages listed in that workflow.

Install just to use these recipes. The platform installer builds a release and adds the app to your desktop. On Linux it links to this checkout, so keep the checkout in place. Quit and reopen Herdr to use the new build.

To compare drawing changes on Windows, Linux or macOS, run the same fixed workloads against each build:

The runner requires hc on PATH and uses the Python executable running the script. It prints a unique artifact folder with the run settings, counters and results, then stops its private app, terminals and core. Both sets use Python fixture programs; the default set’s TUI workload replaces historical btop measurements. --only spinners measures just the quiet native spinner scenario. Keep the window visible and the display awake, and compare the same window activity and display settings; inactive windows may draw at a lower rate. Windows records visibility, foreground activity and display Hz at each measurement boundary; other platforms mark these observations unavailable. Visibility does not establish occlusion. Draws are window render calls. Render-to-paint elapsed time stops before scene finalization, backend drawing, uploads and presentation; it is separate from OS process CPU time. Neither measures physical presentation or the FPS HUD’s derived MAX FPS.

python scripts/bench_compare.py ghostty --root <artifact folder> reuses a run’s fake agent for the macOS comparison. Benchmark checks: python -m unittest discover -s scripts -p test_bench.py.