Herdr on a Mac: Omarchy's zsh setup

My own Omarchy 4 parity doc filed herdr as Linux-only. One line, easy to miss, written by me, and wrong. herdr 0.9 has been sitting in Homebrew for macOS this whole time, minding its own business. The port shipped on 2026-09-08. It took an afternoon. The doc took three weeks to admit it, which is the kind of wrong line the free droid crew checklist is meant to catch before I do.

What herdr is

Omarchy 4 ships herdr beside tmux, and if you already speak tmux the mapping costs you nothing: a session is a workspace, a window is a tab, a pane is still a pane. Nobody reinvented anything. What changed is who it is for. The layouts are built around coding agents, not humans. The dev layout takes an agent name and starts that agent in its own pane, next to an editor and a terminal, like it has a desk now.

The port

Two commands, one config. That is the whole port. I would make it sound harder, but you would check.

COPYbrew install herdr jq
ln -s ~/code/omarchy4mac/herdr/config.toml ~/.config/herdr/config.toml

jq is not a herdr dependency. It is a layout dependency. The layout functions read herdr's JSON through it, so it rides along in the same install and nobody has to think about it again.

The config is Omarchy's own, ported verbatim, because it was already right and I am not in the business of fixing things that work. Two settings carry the whole thing. theme.name = "terminal" tells herdr to draw with Ghostty's palette, so theme <name> reaches it with no template. Every other app in the stack needs a template rendered for it. herdr just borrows the terminal's colours and waits. Smartest app in the room. And onboarding = false skips the first-run screen. You are not a first-run person.

herdr can check its own config, which is more than most of us can say:

COPYherdr config check

The key

⌘⌃↩ opens Ghostty with herdr. It sits one modifier away from the tmux binding, which is either good design or a comment. Take your pick.

• ⌥↩ opens Ghostty.
• ⌘⌥↩ opens Ghostty with tmux.
• ⌘⌃↩ opens Ghostty with herdr.

And h is the alias, because "herdr" is five letters and one of them is missing, and you will type it twice an hour.

The layouts

The layout functions live in zsh/omarchy.zsh, lifted from Omarchy's bash. This is a zsh Mac and Omarchy writes bash, which is the kind of problem that usually eats a Saturday. emulate -L ksh gives each function bash's semantics, so the bash bodies run unchanged. Saturday survived.

• hdl <c|cx|codex|other_ai>: the dev layout. Editor, agent, terminal, one tab. Give it a second agent and it splits the agent pane, no questions asked.
• hds: the square. Editor, a diff watch, a terminal, and opencode.
• hdlm <c|cx|codex|other_ai>: one dev tab per subdirectory. For when the repo is really several repos in a trench coat.
• hsl <n> <command>: a grid of panes all running the same command. For when one pane of it was never going to be enough.

Reload

The binding and the cheat sheet are generated, so refresh them once:

COPYaerospace reload-config

Then reload Hammerspoon. The cheat sheet now lists SUPER + CTRL + RETURN: Ghostty + herdr, as if it had always been there.

The cheat sheet has the whole list on one page as a free PDF, herdr's new binding included.

The omarchy4mac page has the config, the functions, and the changelog, and herdr's own docs are at herdr.dev/docs. A terminal full of agents is the easy half. Keeping them honest is the other one, and that is what the free droid crew checklist is for. The wider desktop it plugs into is the Omarchy Mac one: the tiling, the bar, and the themes. The parity scorecard is one row more honest than it was. herdr was never Linux-only. It was in Homebrew, waiting for someone to look.