flockr and herdr

flockr is a hard fork of herdr by Can Celik and contributors. herdr is licensed Apache-2.0, and so is flockr. Most of the code is herdr's; files in the flockr repository have been modified from it.

Where the fork starts

flockr was taken from herdr's master at commit 143bf5fd, after herdr v0.9.5. Changes before the fork are in herdr's changelog. flockr's version numbers start over at 1.0.0.

For herdr's own docs, see herdr.dev. herdr.dev/llms.txt describes upstream.

Runs beside herdr

You can install flockr and herdr on the same machine. Neither one sees the other. flockr has its own:

binary: flockr
config directory: ~/.config/flockr
socket: ~/.config/flockr/flockr.sock
environment variables: FLOCKR_* (for example FLOCKR_ENV, FLOCKR_PANE_ID, FLOCKR_CONFIG_PATH)
agent hooks: flockr's integrations install their own files, such as ~/.claude/hooks/flockr-agent-state.sh

Install flockr's integrations with flockr integration install even if you already have herdr's. See Integrations.

herdr plugins and configs

Plugins and configs written for herdr work unchanged in flockr:

herdr-plugin.toml plugin manifests and min_herdr_version are accepted.
HERDR_* variables are accepted. A plugin gets every FLOCKR_* variable under its HERDR_* name too.
On Unix, plugins run with a herdr command first on PATH that runs the flockr binary, so a plugin that calls herdr talks to flockr instead of a real herdr install.
delivery = "herdr" in [ui.toast] is read as "flockr".

To move a herdr config over, copy it to ~/.config/flockr/config.toml and run flockr config check.

What flockr adds

A title row with the menu. Agents sit under one header per space, and a worktree's agents nest under their repo the way the spaces list shows them.
All and Active tabs filter the agents list.
Agent rows can show the agent's own branch (branch), following it into the worktree it works in. Space rows show uncommitted changes (diff_stat), worktree spaces included.
Agents and spaces are numbered, with keys to jump to them.
ui.sidebar_position = "right" moves the sidebar to the right edge.

See The sidebar.

Agents

prefix+a steps through agents that are blocked or finished unseen, oldest alert first.
ui.seen_delay_ms and ui.seen_scope: a done agent keeps its done badge until its pane has been on screen long enough, so stepping through agents doesn't clear the ones you pass. prefix+u marks one done again.
ui.keep_agents_in_use_first: a pane whose agent starts a fresh session moves behind the agents in use, and a dotted ring marks fresh sessions.
Resumed agents keep the CLI options they were started with. Codex runs without its shared daemon, so its hooks see the pane.

See Agent states and Jumping between agents.

Keys, layout, and settings

A settings screen in sections; changes save to the config file and apply at once.
The command palette, and vim jump keys in lists.
Link hints, tmux layout presets, and tmux's split and resize keys.
ui.pane_focus_passthrough: ctrl+h/j/k/l move between nvim windows and flockr panes, like vim-tmux-navigator.
Custom command popups are titled with their description.

See Settings, Keybindings, and nvim and pane focus.

Other features

These are covered in their own sections: the flock (several machines' servers seen through one hub), agent messages, the phone app, and the web app. See Flock setup, Agent messages, and Pairing a phone.

What flockr removes

Self-update and background update checks. See Updating.
Downloading agent detection rules between releases (flockr server update-agent-manifests). Rules ship with each release.
The sidebar's priority sort, replaced by the All and Active tabs.