Herdr Control

herdr-control

Small, dependency-light shell tools that drive the **layout** of a [herdr](https://github.com/) session — the terminal workspace manager for AI coding agents — instead of just the messages inside it:

• route an agent session into its own tab of the right project's workspace,
• open a project's workspace on demand (reuse it if it's already open),
• sort a space's tabs by the state of the branch each one is on,
• colour a tab by what it needs from you,
• name each tab after the task its dominant pane is actually doing, and
• surface the one agent that needs you next, with an honest waiting-reason.

They're plain `bash` + `python3` over herdr's control socket. No install step, no framework — clone, edit one config file, run.

Why

With several agents running across repos in one herdr server, tabs pile up in creation order and you lose track of which branch needs a decision versus which is already merged. These scripts put the tabs that need you on top and let you spin an agent into the correct workspace with one command.

Two layers, cleanly split — **Herdr-Plugin Layer** (pure herdr-socket calls; optionally installable as `herdr-plugin.toml`) and **Outside-Herdr Layer** (reacts to Claude Code's/omp's own hook systems, which herdr's plugin manifest can't see). Full definition and the test for where a new idea belongs: [As a herdr plugin](#as-a-herdr-plugin-instead-of-manual-keybindings-herdr-plugintoml) below.

Tools this repo uses (and how to swap them)

Nothing here talks a herdr **plugin** protocol — every script is a thin wrapper over the `herdr` CLI (JSON on stdout) plus a short list of ordinary Unix tools. That's deliberate: no build step, no runtime to install, and every dependency below either degrades cleanly or has a documented swap point, so this stays usable on a machine that doesn't look like the one it was written on.

**Required** — `install.sh` checks `jq`/`python3`/`herdr`/`curl` itself and refuses to wir