Shepherd
Live herdr agent status on your Elgato Stream Deck.
See which of your AI coding agents are running, busy, blocked, or finished — at a glance, on physical keys. Press a key to jump straight to that agent's pane and bring your terminal to the foreground. No more hunting through tabs to find the agent that is waiting on you.
What it does
- One key per agent
- Each key mirrors a live herdr agent: its space name, a status colour, and a two-letter code for the agent type. Rename a space in herdr and the key follows.
- Press to focus
- A short press jumps to that agent's pane and raises the host terminal, so the agent is actually on screen even if the terminal was buried.
- Mirrors herdr's own order
- Keys fill left-to-right, top-to-bottom against herdr's agent panel, including its attention-queue ordering. Nothing to configure.
- A pager that only pages
- Each press advances one page and wraps at the end. A coloured badge flags a blocked or done agent the visible page cannot show — but it is a read-out, never a change of what the press does.
- Notifications, with your own sounds
- When an agent flips to blocked or done, the key flashes and herdr notifies you. Give each status one of the 14 macOS system sounds, or any file you point at.
- Instant updates
- Refreshes on herdr socket events, with a three-second poll as a safety net. No busy one-second polling.
Status at a glance
| Status | Key | Meaning |
|---|---|---|
| working | running now | |
| blocked | wants you | |
| done | finished, unseen | |
| idle | waiting | |
| unknown | — | |
| empty | no agent in slot |
Layout
Two actions, dragged onto your keys from the Stream Deck app. A key's position decides which agent it shows, so there is nothing to configure. The recommended six-key Mini layout:
[ Agent Slot ][ Agent Slot ][ Agent Slot ] [ Agent Slot ][ Agent Slot ][ Pager ]
Keypad-only, and it works on any Stream Deck model with keys — how many agents fit on a page is simply how many keys you placed.
Requirements
- macOS 12 or newer
- Elgato Stream Deck app 7.1 or newer
- herdr 0.7.0 or newer, installed and running
Tested on a Stream Deck Mini with Stream Deck app 7.5.1 and herdr 0.8.0, on macOS 26.5.2 (Apple Silicon).
Availability
Shepherd is not yet published on the Elgato Marketplace. When it is, it will install as a standard double-clickable Stream Deck plugin.
Privacy
Shepherd makes no network requests and collects no data. It reads agent status from herdr on your own machine — over a local Unix socket and the herdr command line — and nothing leaves your computer. There is no analytics, no telemetry, and no account.
Licence
Free of charge, for any purpose including commercial use, on any number of devices you own or control. Redistribution is not permitted. Provided as is, without warranty of any kind.
Support
Questions, bugs, and feature requests: support@fireintheattic.dev