# Agent Deck Herdr's main window rebuilt to show what every agent is doing on every machine. Spaces say what's inside them: chat names, status counts, open shells and running programs. Agents are two-line cards. On the narrow rail, resting the pointer on a row shows its wide card. A full-window Overview (`⌘⇧O`) lays out every agent as a board with one lane per state, and every terminal on every machine with its command and last output lines. ![Overview: agents](preview.png) ![Main window](main-window.png) ## What you see **Sidebar (268px, `chrome` background), top to bottom:** - **Brand bar** (46px): the shipped `workspace-chrome` mod. - **Spaces** (half of the rest, min 90px): - **Machine header** (26px): one per machine when more than this computer is known, with: - a server/monitor icon and the name; - a red `N needs you` badge; - `N terms · M hidden` (tooltip: agents / other / hidden in no space); - `+` (new space there); - a 6px dot, `ansi2` when connected (tooltip: state and `hc` version); - a fold chevron. - **Space row:** - an 18px colored letter avatar and the name (max 150px); - git tail (repo/branch only when unusual, ↑ahead ↓behind); - status counts in status colors (`1 needs you`, `1 working`, `2 idle`); - `N shells · M busy`. - **Under the row**, up to 4 lines (11.5px) per kind, then `+N more`: - its agents' chat names, each with a status dot; - its shells/programs: program icon, program name, and the folder (or the program's own title while busy, unless that is a path, a prompt or just the terminal id). - **Divider:** a 12px gap with a 2px `dim` line (the layout's `divider` on `sidebar-lists`); drag it to resize. - **Agents** (the other half, min 90px). Its header `Agents ⌄` rolls Spaces up (`layout.toggle {id: "spaces"}`); `Agents ›` shows it again. On the rail the same chevron sits above the list. Grouped by space, or by priority (Needs you / Done / Working / Waiting / Idle) with the sort menu. Each agent is a card (8px radius, `surface` background, `border`; focused: `selected` background and `accent` border): - **Line 1:** program icon, chat name (semibold), the fold chevron with sub-agent count, time in state (a pin on hover), status mark. - **Line 2:** chips `@machine` (`@local` here) and the space name. - **Agents footer** (28px): on the left a layers icon (Overview), a board icon (Harness board) and a search icon (History), 12px apart; at the right `«` (tooltip `Narrow the Agents column`) narrows the sidebar to the rail. On the rail it is 98px and stacks the three icons over `»` (`Widen the Agents column`), which brings back the width it had (268px by default). - **Copy link on Agents cards:** resting on a Claude Code card (program key `claude`) shows a 12px link icon before the pin, as on Overview cards: `ansi2` for 2 s after a copy, `blocked` when there's no session to link yet. The rail's hover cards have it too. - **Sidebar footer** (69px): the shipped `workspace-chrome` footer. **Narrow rail** (under 160px wide, 76px on macOS), the cells as in herdr-app [PR #286](https://github.com/herdrdev/herdr-app/pull/286), centered: a space is its 22px colored avatar (a branch mark for a worktree), 34px high (30 for a worktree), with a 9px status dot on its corner when it needs you; the active one has the `selected` background, and right-click opens its menu. The `+` above them is centered. An agent is its program's 16px icon (its number when it has none) and its status mark, or, when its terminal has a `task` or `role` label, a badge instead of the icon: the first letter of `task`, then of `role` (a missing one leaves its place empty), bold 10.5px on an 18px-high block (22px wide at least, 5px radius) in its task's color (`agent-deck-agents/badge.js`). There are 10 colors that can't be confused (red, orange, yellow, green, teal, blue, purple, pink, brown, grey), one palette per appearance (`settings().dark`), each with its letters (white or dark) at 4.5:1 or better and standing out from that sidebar. A task's color is the one chosen for it in the label editor, else its home color (FNV-1a of the task name, mod 10), else, when a task above it on the rail has that, the next free one; a task keeps its color while it stays listed, so with 10 or fewer tasks on screen no two share one. A session with only a role goes by that role; 30px high, 8px radius; the focused one has the `selected` background and an `accent` border. The `«` / `»` button is 26px with a `hover` background. Resting on any row for 250ms opens its wide card to the right: - an agent card is 300px wide and includes its sub-agents; - a space card is 320px wide. The cards use `popover` background, `border` and `shadow_lg`. **Main area:** the tab bar (42px), panes, a `files`/`changes` panel (368px) and the `workspace-status` bar (28px). These are Herdr's main layout, except that the tab bar is `agent-deck-tabs`: the shipped `tabs` with a 26px tag button left of `+` (Lucide `tag`, 14px, `dim`; `border` color when no terminal is focused). Its tooltip lists the focused terminal's own labels (`Labels: role=lead · task=PROJ-1`), or says `Add labels (role, task…)`. **Pane header** (`agent-deck-pane`): Herdr's shipped pane header, plus the terminal's own labels (not `where`, not `herdr.*`, not empty) right-aligned after the folder, before the status mark and the hover buttons. They're chips like the Overview's, sorted by key: `key` in `dim`, the value in `foreground`, 10.5px, `chrome` background, `border`, each cut at 220px (tooltip `key=value`), 480px at most for all of them; the folder shrinks first. **Label editor** (`agent-deck-labels`): a dialog 560px wide, `popover` background, 16px padding. - **Header:** tag icon, `Labels`, then ` ·
` in `dim`. - **Rows:** `Role` and `Task` always (a 64px label, then a 28px field with the `accent` border while focused); then one row per other label the terminal has: a 120px key field, the value field and a `×`. - **Suggestions:** under the focused value field, up to 8 clickable chips (11px, `chrome` background, `accent` border on hover). - **`+ Add label`** adds a key/value row; an error line (`blocked`) when a key is refused or `hc label` fails. - **Footer:** `Enter saves · Esc cancels · an empty value removes the label`, `Cancel` (bordered) and `Save` (`accent` background; `Saving…` while it runs). **Harness board** (`harness-overview`, `⌘⇧H`): a dialog 92% × 90% of the window. Its data comes from a script you name in `~/.config/herdr-app/data/harness-overview/config.json`; the format, the commands and an example script are in [`mods/harness-overview/README.md`](mods/harness-overview/README.md). - **Header:** `Harness`, the manager session chip, where the data came from and how old it is, a filter box, a `Task` drop-list (as the Overview's), `Drafts (N)` (accent while there are drafts), `Refresh`, ✕. - **Four columns** (as the Overview's lanes): **Needs you** (Urgent, then Decide cards; Urgent ones with a `blocked` border), **Reviews** (Ready to merge, then On review), **In progress** (a `Blocked sessions N` box, then tasks with `waiting on you` ones first, then an `FYI (N)` toggle), **Questions** (answered batches with `OK`, then the ones still waiting). - **Card:** id and group, age; the text as markdown (`TextView`) with clickable links, cut at 260 visible characters with `more`; links to sessions go to them, others open in the browser; chips for tasks, sessions (status dot; a running one goes to it) and links the text doesn't show; saved drafts with ✕; `Answer` opens a 4-row box with `Send` (now, this card only), `Save draft` and `Cancel`. - **Drafts dialog** (760×640 over a dimmed board): drafts by card (title, where, excerpt), each note with its time, ✎ (edit in place: `Save` / `Cancel`) and ✕; `Send this card (N)` per card; `Close` and `Send all (N)` at the foot. A click outside or `Esc` closes it. - **No config:** `No board script configured`, the file's path, the example to try, and the format. **History** (`agent-deck-history`): a dialog 720px wide, 70% of the window tall, `popover` background, 16px padding. - **Header:** search icon, `History`, then `N past sessions on M machines` (`Reading devbox, …` while scans run). - **Search box** (34px, `accent` border while it has text): `Search past sessions, or paste a herdr-resume:// link`; it has the keyboard when the dialog opens. At its right a `Full text` check button (a 14px box, `accent` with a check when on). - **A small heading:** `Recent`, `Matches (N)` (`N+` at the limit), `Full text: N sessions · searching devbox…` or `This session` for a pasted link. - **Full-text rows** grow a third line: the matched line in the terminal font, 11px, `chrome` background, the match semibold in `accent`, the words before and after it `dim` and cut with `…` (tooltip: the whole shortened line). - **Rows** (46px, 8px radius, `surface`, `border`; the picked one `selected` with an `accent` border): a clock icon (a `working` dot when the session runs now), the title (13px) over `machine · folder` (11px, `dim`, server or monitor icon, home as `~`); on the right `running` (a `working` pill) or the age (`5m`, `3h`, `2d`); on hover `Copy link` (`Copied` for 1.5 s); `Opening…` while it opens. - **Footer:** errors per machine (`blocked`), then `↑ ↓ pick · Enter opens · Esc closes · …`. **Copy link on Overview cards:** a Claude Code card (program key `claude`) has a 12px link icon (Lucide `link`) before its tag icon; `ansi2` for 2 s after a copy, `blocked` when there's no session to link yet. **Overview:** a dialog at 85% × 85% of the window. - **Title row** (44px): `Overview`, the tab switch `Agents N | Terminals N`, the machine count, a filter box (up to 360px, `search` icon, `accent` border while it has text), a `Task ▾` menu (28px, up to 240px, `accent` border while it filters; the open list is a 280px popup under it, up to 360px tall, with `All tasks`, every task and `No task`, each with its count on the current tab), status pills (Agents tab only), a bordered `Usage` button (Terminals tab only; `Usage…` while measuring) and a close button. - **Machine strip:** one chip per machine with a connection dot, `N agents · N terms`; the tooltip shows the state, `hc` version and hidden terminals. - **Agents tab:** four lanes, left to right: - **Working** (`working` color), **Needs you** (`blocked`), **Done** (`done`) and **Idle** (`idle`), each with a 2px colored underline and a count; - the Working lane also holds **waiting** agents (state word and pill in `muted`), after the busy ones; - inside a lane, agents are grouped by machine (small header, count); - cards are at least 240px and wrap several to a line; - an empty lane shrinks to 150px and says `None`. - **Terminals tab:** one lane per machine. The header shows the count, `N running` and `N hidden`, and on a connected machine a `+` at the right (tooltip `New space on `); the underline is `ansi2` when connected. After `Usage` was pressed, a 24px row under the header reads `CPU 12% · MEM 47% · Disk 81%` (labels `dim`, values semibold: `foreground`, `working` from 75%, `blocked` from 90%, `–` for one it could not measure); `Measuring…` while it runs, or `Usage: ` (tooltip: the full reason) for a machine that is not connected or did not answer. Cards are at least 260px. Each card shows: - the program icon; - the command as typed (`make test`), `zsh` for an idle shell, or the chat name for an agent; - a state word: `running` (accent), `idle`, or the agent's status; - the folder, `space / tab` (or `hidden` in `done` color) and its age; - the last 2 non-empty screen lines in the terminal font (an agent shows its last report message instead). - **Labels on cards (both tabs):** an agent card has a 12px tag icon (`dim`) before its status mark or word. A card whose terminal carries labels of its own (not `where`, not `herdr.*`, not empty) shows them as chips under its second line, sorted by key: `key` in `dim`, the value in `foreground`, 10.5px, `chrome` background, `border`, cut at 200px (tooltip `key=value`), wrapping to more lines. ## How it behaves **Status:** - **working:** yellow dot, or a spinner in the Agents list. - **blocked:** red: `needs you`, `!` in priority view, a red card border in the Overview. - **done:** blue, until you look at it; then it is idle. - **idle:** a grey ring or dot, with dimmed names. - **waiting:** an `idle` agent whose 7501 record `bg` is `working`: a slow grey spinner (2.4 s a turn) in its own Waiting section, and in the Overview's Working lane. A `done` agent stays done until you look at it, whatever its records say. The `bg` record comes from a hook, such as the Claude Code hook in [herdr-agent-waiting-mod](https://github.com/zztalker/herdr-agent-waiting-mod) (needs an hc with `hc report`, [herdrdev/herdr-core#81](https://github.com/herdrdev/herdr-core/pull/81)). Without it no agent waits and nothing changes. - **Cursor:** Cursor Agent CLI reports no status (no OSC 7501), so Herdr shows its pane as a program. The Cursor hook in the same repo reports its idle, working and done with `hc report …:app=cursor`, and it is listed like any other agent, with Cursor's icon from Herdr's program table. Its installer, `agent-waiting/hooks/install.sh`, puts in the hook of each agent it finds (Claude Code, Cursor) on the machine it runs on. **Clicks:** - An agent card or row focuses its pane. - A space row selects the space; right-click opens its menu; dragging reorders spaces. - A machine header folds that machine. - Overview: - an agent card runs `agent.focus` and closes the Overview; - a terminal card in a pane runs `pane.focus`; - a hidden terminal (in no space) runs `terminal.peek`; - a Terminals lane's `+` runs `space.new {machine}` (empty for this computer): a new space with a shell in that machine's home. Then the Overview closes. - `Usage` measures this computer and every connected machine in parallel; each lane fills in as its answer comes. Pressing it again while a machine is still measuring skips that machine. - a card's tag icon opens the label editor for that agent (it stops the click, so the card doesn't also go to the agent); - `Task ▾` opens its list; picking an entry filters and closes it; clicking `Task ▾` again or `Esc` closes it. - The tab bar's tag button opens the label editor for the focused terminal, agent or shell (nothing when no terminal is focused). - Label editor: - clicking a suggestion puts it in the field; - `Save` or Enter in any field runs `hc label
k=v… k=…` with only what changed (an emptied value or a removed row sends `k=`), remembers the role and task in the mod's localStorage, and closes; nothing changed just closes; - a **Color** row under the label rows: `Auto` (a pill, `accent` border when chosen) and 10 20px color dots (`accent` ring on the chosen one), with `For every session of task ` below, or `Set a task to give it a color` (dots faded) while Task is empty. Save stores the pick for the task in the Task field, in shared state `agent-deck.task-colors` (`{task: color name}`; `Auto` removes the task), even when no label changed; - `Cancel` or `Esc` closes without writing. **Filter:** typing goes to the filter box as the Overview opens. Every word must appear on a card (any case), or the card is hidden: - an agent: chat name, program, state word, space, tab, machine (`local` for this computer); - a terminal: command, folder, `space / tab` or `hidden`, address, title, last lines, machine. The task menu filters too: a card shows only if its terminal's `task` label is the picked one (`No task`: it has none). Both filters apply together. While either is on, the tabs read `Agents 3/9`, the pills count only what matches and empty lanes say `No match`. The last pick is remembered (localStorage `taskFilter`) and applies when the Overview opens again; a stored value it can't read means all tasks. **Suggestions** in the label editor: values of that key from every live terminal on every machine; for `task` and `role` also the values saved before, kept in `agent-deck-labels`' localStorage (`tasks`, `roles`, most recent first, 50 at most), listed first. Matching is anywhere in the value, any case; values starting with what was typed come first; the value already typed is not offered; with nothing typed, the first 8. The `×` or `Esc` clears it; `Esc` again closes the Overview. **History:** - Empty box: Recent, the 8 newest past sessions not running now. - Typing: sessions where every word appears in the title, the folder or the machine (`local` for this computer), any case; newest first, up to 50; running ones included and marked. - A pasted `herdr-resume:///` (or a bare id): that session only (on any machine for a bare id). - ↑ / ↓ move the highlight, Enter or a click opens: if the session runs in a terminal now (a pid in `~/.claude/sessions/*.json` on its machine that a live terminal there runs), `agent.focus` on it; else `claude --resume ` with `tab.new` in a space on its machine (the one whose folder is the session's first), else `space.new` there, in the session's folder or its nearest existing parent. Then the dialog closes. - Every reachable machine is scanned when the dialog opens; each fills in as it answers. - **Full text** (remembered in localStorage `full`): with at least 3 characters typed and 0.4 s since the last key, each scanned machine runs `FULLTEXT` with the text; the list is then the sessions it reports, newest first, up to 50. A machine that answers later fills in then; an answer for older text is dropped. A pasted link still finds that session only. - `agent-deck-history.full` toggles Full text; `agent-deck-history.search ` sets the search text. **Resume links:** `herdr-resume:///`, `local` for the Mac the link is clicked on. `resume-link/install.sh` registers `~/Applications/Agent Deck Resume Link.app` for the scheme; it runs its copy of `agent_deck_resume.py`, which checks the machine is in `hc machine ls`, reads the folder from the session's own transcript there (never from the link), starts Herdr if needed and then shows or reopens the session as History does. Errors are macOS notifications; the log is `~/Library/Logs/agent-deck-resume.log`. **Keys and commands:** - `⌘⇧O` (`mod.open:agent-deck-overview`) toggles the Overview; `Esc` closes it. - `⌘⇧H` (`mod.open:harness-overview`) toggles the Harness board. `Esc` closes the answer box, then clears the filter, then closes the board. It reruns ` json` every `every` seconds (default 120) while open and not answering, and after each button; a failed run keeps the last board and says so in the header. - `agent-deck-overview.agents` and `agent-deck-overview.terminals` switch its tab while it's open. - `agent-deck-overview.usage` switches to Terminals and measures, like the button. - `agent-deck-overview.label` opens the label editor for the focused agent; `agent-deck-overview.tasks` opens or closes the task menu; `agent-deck-overview.task ` filters to that task (`task` alone: all). - `mod.open:agent-deck-labels` opens the label editor for the focused terminal (the tab bar button does the same). - The tab you used last is remembered. **Tab names:** a tab holding exactly one agent with a real chat name takes that name, cut to 48 characters. It's checked every 3 seconds and follows the chat if it's renamed. Herdr's own alerts then read `Claude Code needs you`, then `space / ` instead of `space / 1`. Tabs someone named stay as they are, so History opens its tabs unnamed (`openPlan`). The tab bar shows the same title for a tab that is unnamed or named only after its program (`Claude Code`) (`agent-deck-tabs/name.js`). A title counts when it isn't the program's name, a path (`~/…`, `/…`, `C:\…`) or `user@host`, after Claude's status glyph (`✳ `) is dropped (`agent-deck-agents/title.js`; `name.js` has a copy). Clearing a tab's name (an empty `tab.rename`) hands it back. `NAME_TABS = false` at the top of `agent-deck-agents` turns this off. **Refresh:** - Machines: every 15s (Spaces) and 30s (Overview). - Terminal output lines: every 8s, one `hc read` at a time, only while the Terminals tab shows. - Usage: never on its own; only when `Usage` is pressed. The numbers stay until the next press or until the Overview reloads. ## Built from - **`layouts/agent-deck.json`:** a clone of Herdr's `main` layout with `spaces` → `agent-deck-spaces`, `agents` → `agent-deck-agents`, `tabs` → `agent-deck-tabs` and the pane header `pane` → `agent-deck-pane`. - **`mods/agent-deck-tabs`:** `mod.clone` of the shipped `tabs` (Herdr 0.1.13, `cloned_from` in `mod.json`). A tab's label comes from `tabName(tab, lead)` in `name.js` (node-tested in `name.test.mjs`). It adds `labelButton(t, button)`: the tag button before `+`, from `focused().terminal` and that terminal's `labels` in `terminals()`, opening `openOverlay({ mod: "agent-deck-labels", kind: "dialog", width: 560, props: { terminal } })`. - **`mods/agent-deck-pane`:** `mod.clone` of the shipped `pane` (Herdr 0.1.14, `cloned_from` in `mod.json`). It reads the pane's terminal's `labels` from `terminals()` and adds the chips after the folder. `labels.js` (no imports): `headerLabels(labels)`, the `[key, value]` pairs to show. Tests: `labels.test.mjs`. - **`mods/agent-deck-history`:** new, `mod.json` overlay `{ kind: "dialog", width: 720, height: 0.7 }`. - `history.js` (no imports, node-tested in `history.test.mjs`): `SCAN` (the per-machine scan), `parseScan`, `parseLink`, `search(rows, query, limit = 50)`, `recent(rows, n)`, `shortPath`, `resumeLink`, `SESSIONS` / `sessionPids` (running sessions: each session file, and a running one again under its parent's pid; `resume-link/agent_deck_resume.py` has a copy), `NEAREST` (nearest existing folder) and `openPlan(spaces, row, folder)` (the `tab.new` / `space.new` to run). - `SCAN`: `stat` (GNU, else BSD) lists every `~/.claude/projects/*/*.jsonl` with its change time and size; ones not in `~/.cache/agent-deck-history/index.tsv` are read with `grep -oE` for `cwd` (first), `timestamp` (last), `customTitle` / `aiTitle` and `entrypoint` (`sdk-*` is left out), each row appended to the index at once; then the index is tidied to the last row of each file that still exists. Then `liveid` for each session file whose pid runs (`kill -0`). - `FULLTEXT` (the text as `$1`): for each transcript the index lists, `grep -v -F` drops `"type":"attachment"` and `"type":"api-request-blob"` lines, `grep -F` keeps `"type":"user"` / `"type":"assistant"` ones, then `grep -m1 -i -F --` finds the text; awk prints up to 400 characters around it. `parseHits` reads that; `snippet(raw, query, width = 60)` unescapes JSON and cuts it to whole words around the match. - It runs everything as `hc exec [--on m] --timeout 120 -- sh -c