# Sheepdog Manage your Herdr agents by voice. [Sheepdog](https://github.com/kccarlos/herdr-sheepdog) keeps watch on your coding agents, tells you what finished and asks when one needs a decision. This panel shows that conversation beside your agents, the same one as on your iPhone: reply by voice, by typing or with a tap. Needs the Sheepdog program on the same computer. ![Sheepdog](preview.png) ## What you see **One block, two shapes.** Docked on the right (340 px by default, on the `chrome` background) it is the panel below. Narrower than 160 px it is the rail; a window (the rail opened it, or `mod.open` did) is always the panel. "Needs you" is the phone's amber, `#D98718` on a light sidebar and `#F39C1F` on a dark one (told from the `chrome` colour's luminance, since `theme()` has no light flag), used wherever this text says `blocked`; the theme's own `blocked` is red. **The rail** is a compact column: the logo (26 px), the voice dot, and, when agents need you, a `blocked` badge with the count; the whole column is the button (it opens the panel as a window) and its tooltip says the state. The dot is `done` while listening, `idle` while muted, `working` while connecting, speaking or waiting for the voice, `blocked` in setup needed and `dim` otherwise. The voice's words, from the daemon's `voice` in `/api/state`: "Voice off", "Connecting", "Voice not connected", "Waiting for the voice", "Ready" (nobody holds the voice; on a Mac it reads "Sheepdog.app isn't installed", "Sheepdog.app isn't running" or "Connecting to Sheepdog.app" instead, with an **Open Setup** or **Open Sheepdog.app** button), "Listening", "Muted", "Speaking" (this Mac holds it), and "Voice on iPhone" (or "…on a browser", else the client's name), with ", muted" or ", speaking" added, when another device holds it. This Mac is the holder whose `voice.client.platform` is `macos`. **The panel**, the docked block or a 420 × 640 window, on the `chrome` background. Top to bottom: the header, the banners, the voice controls, the floating question, the composer, and the timeline filling the rest (6 below is a card opened over the timeline). The timeline always keeps at least 55% of the height. `model/layout.js` gives the header and composer their space first, then caps the banners, voice controls and question in a scroll area; a short panel makes each docking or setup banner one line and may make suggested replies one sideways-scrolling row. The composer is outside that area, so it stays visible. 1. A header, 12 px padding, a 1 px `border` under it, two lines (three when agents exist). First: the logo (20 px), "Sheepdog" (13 px semibold), a `blocked` pill ("1 needs you", "2 need you") with `solid_foreground` text when agents need you, a **⋯** menu button, and, in a window, a ✕ that closes it. Second: the voice dot (7 px) and words (11.5 px, `muted`, truncated) and a **Technical** text button (11.5 px, `muted`). When agents exist, a third line (11 px, `dim`, truncated) counts them by group from `/api/state`'s `agents`, skipping empty groups and those not running: "1 needs you · 2 working · 1 done" (the daemon's `attention.group`, else the agent's state for an older daemon; `model/agents.js`). The pill and the rail's badge stay the open questions only; when the pill shows the same needs-you count the line leaves that part out ("2 working · 1 done"), so it is not said twice. The controls stop the press so the rest of a window drags. - **Voice controls**, under the banners, in a 12 px padded bar with a 1 px `border` under it, when the daemon answers: four 26 px outline chips that wrap, **Talk**, **Mute**, **Stop** and **Hold to talk**; a chip that cannot work now is at 40% opacity and does nothing. Which work (model/voice.js's `voiceControls`): with nobody holding the voice only Talk (it runs `open sheepdog://talk`); with a holder (this Mac, or the phone, the daemon relays) Mute while not muted, Talk (unmute) while muted, Stop only while it speaks, Hold to talk always; with `voice.mode` "off" none, with "The voice is off." The Hold to talk chip sends `POST /api/voice/ptt {on:true}` on the mouse down and `{on:false}` on the mouse up (`solid` while held; a hold never released closes itself after 30 s, and closing the mod releases it). Talk unmutes with `POST /api/voice/mute {on:false}`, Mute is `{on:true}`, Stop is `POST /api/voice/stop`. When another device holds the voice, or a call answered 409, a **Use here** button (outline) runs `open sheepdog://talk` through `exec`. A 409 reads "No voice is connected" under the chips (a 503 gives the daemon's reason, no answer "Sheepdog did not answer. Try again."), and a failed `open` says "Sheepdog.app did not start. Install it with: brew install --cask kccarlos/tap/sheepdog-app". Whether `/Applications/Sheepdog.app` or `~/Applications/Sheepdog.app` exists is looked at (read-only) every 30 s: with neither and nobody holding the voice every chip is off and the bar says "Sheepdog.app is not installed, so there is no voice on this Mac." with `brew install --cask kccarlos/tap/sheepdog-app` in a `raised` box; with the phone holding the voice its controls still work and Use here is off with the same words. Off a Mac none of this applies: the app is not looked for, and with nobody holding the voice the chips are off and the bar says "Open Sheepdog on your phone to talk." Notes go after 8 s. 2. A banner when it applies: in a window that the docked rail did not open (`mod.open`; the rail's window gets the prop `docked: true`), "Put Sheepdog in the sidebar" (12.5 px semibold) with two `muted` lines (this is the fallback; a layout that ships with herdr-app cannot be changed, so copy it to make it yours, then add the block for the mod `sheepdog` on its right side) and a **Copy my layout** button that runs `layout.clone` with the name `shared("layout")` (it switches to the copy and closes the window; a `blocked` line says when herdr-app refused); the daemon-down text as the whole body (title "The Sheepdog daemon isn't running", the reason when something other than sheepdog answered, "Start it, or run setup if this is the first time. In a terminal:", `sheepdog start`, a primary **Start Sheepdog** button that runs it and an outline **Run setup** button that opens `sheepdog setup` in a tab, "Looking again every 3 seconds."); the setup-needed block under the header (title in `blocked`, the daemon's words, a primary **Run sheepdog setup** button); the dashed "Live updates paused" line. 3. The timeline, newest first, with a scrollbar. Each day has a heading, "Today", "Yesterday" or "Monday 21 September" (with the year when it is not this one), between two hairlines, above that day's rows. Times are 24 h local, "17:42". Rows by category (docs/dev/design/conversation-timeline.md): - **Dialogue**: bubbles, 14 px radius with one 6 px corner, at most 4/5 of the width. You are on the right (`accent`, `accent_foreground`), the voice on the left (`raised`, `foreground`). A 10.5 px `dim` caption says "Typed" under your typed lines and "Sheepdog wrote" under a reply that was written. - **Needs you**, the only amber: an open question, or a push that interrupts, as a pointer: `blocked` at 12% fill, 1 px `blocked` at 33% border, 10 px radius, a 8 px `blocked` dot and "Codex asked — waiting for your answer" (the agent's name, else "An agent") on one line (two words in a wrapping row, so a narrow block wraps between them, never inside the dash), the question's words under it in `muted`. Newest first it sits above the words that led to it, so it has the normal 18 px from the row below, not the phone's 4. - **Outcomes**, lines of a ledger: consecutive lines share one `raised` card with a 1 px `border` and 10 px corners at the ends of the run. A 28 px well leads each: a round one with `>_` (`working` on `working` at 15%) for an agent's news, `✓` (`done` on `done` at 15%) for an approved question, `×` (`foreground` on `hover`) for a declined one, a hollow `border` ring with `–` (`muted`) for one that expired, was replaced or closed; a square well with `▢` for a card. The line is the agent's name (11 px, semibold, `muted`) over the words (12.5 px) over the time (10.5 px, `dim`). A settled question reads "You approved — Yes, proceed · by tap" or "Codex's question (allow Computer Use to use Finder) — closed". - **Context**: a hairline with a centred 11 px `muted` caption: a day, "New conversation · 17:42", "Sheepdog restarted · 17:42", "Sheepdog updated to v0.9.1 · 17:42", and "Voice restarted — it may not remember the last minute · 17:42" when the voice lost its context within 5 minutes of dialogue. Consecutive "Sheepdog restarted" dividers become one, showing the newer time. - **System** (reconnects, a closed voice session, kinds this build does not know): not listed, except under **Technical**, where every row shows with its three-letter code (DLG, ASK, UPD, CTX, SYS) in a gutter and a dashed 1 px `border` box for the plumbing. - The last row says "Earlier messages", "Loading earlier…", "Earlier messages aren't shown here" at the memory limit, or "This is the start of the conversation" in a dashed box. 4. With no history: "Nothing has been said yet." centred in `dim`. 5. Above the timeline, under the voice controls, when the daemon answers (also in setup needed), from the top: - **Open questions** (the daemon's `questions`, else `pending_action`; only worker prompts with options), a card each with 8 px between: a 7 px dot (`blocked`; `done` once settled), "Codex needs your answer" ("Codex asked" once settled; "An agent" without a name) at 12 px semibold, the question's words (12.5 px semibold), the command (11.5 px monospace in a `raised` box), and one full-width button per option: `raised`, 1 px `border`, 8 px radius, the label (12.5 px semibold), a "Recommended" tag (`blocked` at 12% fill) when the agent recommends it and the description under it (11.5 px, `muted`). No option is filled. The first card has a 2 px `blocked` border, the others 1 px `border`. A tap or pressing 1-9 on the panel sends `POST /api/pending/answer`; the buttons show "Sending…" and wait for it; the card then reads "✓ You chose Yes" (`done` border) and stays four seconds after the daemon stops listing it. A 409 reads "That question was already answered or has gone." and asks `/api/state` again; any other error shows under the buttons and leaves it open. - **Compact**: when the cards' estimated height passes the question area left by the vertical budget (back to inline under 85% of that, and never while the questions sheet is open or an answer is on its way) they are one 36 px bar, `blocked` at 12% with a 1 px `blocked` 33% border: a dot, "Codex asked" ("2 questions need you") and "Answer" in `blocked`. Clicking it (or pressing `a` on the panel) opens the cards over the list, with a **Close** button. The heights are estimated from the words and the window's width (the runtime has no measuring a render may use), a simplification of the phone's measured rule; using only the remaining top-stack height makes a short window compact sooner. - **The composer**, 12 px padding and a 1 px `border` below: when a suggested reply is live, "Suggested replies" (10.5 px, `dim`) over outline buttons that wrap, or a single horizontally scrolling row in a short panel; then the textarea (1 to 5 rows, 13 px) in a `raised` box on light themes (`input` on dark), 1 px `border`, 8 px radius; then the hint "Enter sends · Shift+Enter for a new line" (10.5 px, `dim`), "Waiting for the reply…" while a line is on its way, or the note of the last send: an error in `blocked` ("the orchestrator is off (…)", "Sheepdog did not answer. Your text is kept; send it again to retry.") or "Answered by voice." in `muted`, which goes after six seconds. A voice bubble is `selected` with a border on light themes and `raised` on dark. 6. A card the orchestrator showed is a ledger line with a `▢` well, its title, "Card · Codex · 17:42" and a `›`. Pressing it (the list's `on_item_click`) opens the card in place of the list: a bar with the title, "Card · Codex" and **Close**, then the body, then, when the card has a `pane_id`, a primary button "Show Codex in herdr" ("Show the agent in herdr" without a name) (a `blocked` line under it says when herdr-app refused). A `card` is markdown: headings in bold, bullet and numbered lists, fenced code in a `raised` monospace box, tables as a `raised` box with a bold header row and hairlines (`:---:` alignments kept), paragraphs; bold, italic and links are shown as their words. An `excerpt` is the agent's screen lines in monospace, an `approval` card its question, command and options read-only ("Answer it in the question card."), an `agent` card its title. Every colour is a `theme()` name, so dark and light both work; the only computed colours are `blocked` and `working` and `done` with an alpha suffix. The light composer and assistant bubble switch between theme tokens for clearer separation without changing dark. The logo is `logo.svg` with its cream sticker outline, drawn with `image()` (which keeps colour; `svg()` would tint it to one). ## How it behaves - The data layer asks the daemon: `GET /api/state` and `GET /api/conversation?limit=50` (and `&before=` for older pages) with `fetch`, and `GET /events?kinds=agent,card,conversation,daemon,herdr,pending,space,voice,web&since=` over a raw TCP socket (`net.connect`), because `fetch` is buffered. The overlays also read `/api/agents`, the voice and orchestrator model routes, `/api/settings`, `/api/devices`, `/api/pair` and `/api/pair/qr.json`; their changes use the matching `PUT`, the confirmed device `DELETE`, and the other routes described below. The mod reads the chunked HTTP body itself and parses `id:`, `event:` and `data:`. Every record, the `: keepalive` comments the daemon sends every 15 s included, proves the stream is alive; after 40 s without one it reconnects, waiting 1 s, then 2, 4, 8 and 15 s while that fails, and sends `Last-Event-ID`. - An event that can change what is shown (a question, a push, an utterance, a reset, a restart, who holds the voice, mute, speaking) makes it ask `/api/state` and `/api/conversation` again; an agent's state change (`herdr.transition`), its attention or a space mute asks `/api/state` only. Rounds are at least 40 ms apart (`MIN_GAP_MS`, so a burst costs a request or two), and events whose words are already shown (transcript fragments, `pending.*`, `voice.push`, `web.utterance`) wait for 0.7 s of quiet (`QUIET_MS`). While the stream is live it also asks both every 30 s (`CHECK_MS`), in case an event was not enough. Those events' payloads are folded into the list at once (`model/fragments.js`), before the daemon's page replaces them by id. Other events (audio stats, playback, usage) change nothing. Items merge by id, the server's copy winning. - While the stream is down it asks every 3 seconds instead and shows "Live updates paused". If nothing answers the daemon is down, with the same 3 s retry. - The list pages back when its last row is drawn: it asks for the next older page (`before`), and the rows are added below, so nothing moves under you. - **Technical** shows every row the daemon sent; without it only what was said, what needs you, what agents did and where you are. - A docked block 160 px wide or more is the panel (`.on_size_change` reports the width; before the first report it is taken as 340). Narrower, it is the rail. Clicking the rail opens one window with `key: "sheepdog-panel"`, `keep: true` and the prop `docked: true`: opening it again replaces it, and it returns after a restart. The ✕ closes it for good. `herdr-app do mod.open --name sheepdog` opens the same panel as a dialog without that key and without `docked`, so it shows the docking hint. - **Docking.** A mod cannot put itself in the sidebar: herdr-app changes a layout only through `layout.set` (a whole tree, personal layouts only), and the tree's shape is not in the runtime's notes, so the mod does not guess it. herdr-app docks a mod the first time it sees the folder, into a layout you own, from `mod.json` (`place`, `size`). A shipped layout is replaced at start, so the window offers **Copy my layout** (`run("layout.clone", { name: shared("layout") })`); the user then adds a block for the mod `sheepdog` to the right side of the copy. That second step is the user's. - **Voice.** The controls POST to the daemon, which relays them to whoever holds the voice (this Mac's Sheepdog.app or the phone), so the mod never asks who it is; the one thing it cannot relay is Use here, `exec("open", ["sheepdog://talk"])`. Hold to talk is a mouse down and a mouse up on one element (`on_mouse_down`, `on_mouse_up`); a release outside it is never seen, so a hold ends after 30 s on its own, and its on and off requests go in order. - The header's **⋯** menu opens three separate overlays: **Settings** (voice and orchestrator models, languages, reply style, paired devices with a two-step Unpair, and `/api/state`'s update notice), **Pair a phone** (a QR drawn with `div()`s from `/api/pair/qr.json`, the `/api/pair` link as plain fallback text, and **New code**, which calls `/api/pair?new=1`), and **New conversation** (a confirmation before `POST /api/conversation/reset {via:"app"}`). AI-service consent is phone-local today and has no daemon route, so this desktop Settings has no consent toggle. - A press on a timeline row that names an agent opens its details from `GET /api/agents`: what it works on, its last result and detail, its last question and answer, and its space. A card row still opens the card instead. - The buttons **Start Sheepdog**, **Run setup** and **Run sheepdog setup**: **Start Sheepdog** runs `sheepdog start` (looking in `~/.local/bin`, `/opt/homebrew/bin` and `/usr/local/bin` first), and the setup buttons run `terminal.open` with `argv: [, "setup"]` in a tab. - **Sending, queueing and reload persistence.** The textarea's `submit` event sends, never `change` (an input method's commit fires `change`), while `change` saves unsent text in `shared("sheepdog.draft")` (1 h TTL). A textarea inserts the Enter's newline and also fires `submit`: with shift nothing is sent (the newline stays); without it the value minus ONE trailing newline is the text and the box is cleared; a value that is only whitespace never sends (and is cleared). `POST /api/turn {text}` carries an `Idempotency-Key` (`panel-