# Control Tower A quiet night-console window for watching agents. A thin rail of space tiles runs down the left and a Pulse board down the right. Across the top, four fixed runways hold your agents as aircraft: TOWER (needs you), RUNWAY (working), APPROACH (done while you weren't looking) and TAXI (idle). Each aircraft is a small side-view plane with its session name under it. When a status changes the aircraft slides to its new runway. Everything is ink-grey; status color is only a dot beside each runway name, the runway edge lights and the plane, and amber marks the agent you're focused on. Terminals sit below as rounded cards. ![Control Tower](preview.png) ## What you see Left to right, then top to bottom: - **Rail** (column, 64 px, not resizable, drags the window, `chrome` background `#07080d`): three blocks stacked top to bottom. - **Space tiles** (takes the remaining height): content starts 44 px from the top (room for the traffic lights at [12, 16]), is centred horizontally and puts an 8 px gap between tiles. One 32 px square tile per space, radius 8, `#11141c` with a 1 px `#1d212b` hairline, holding the space name's first letter uppercased (13 px, weight 500, `#a3a9b8`). The shown space's tile is `#1a1e28` with an amber letter `#f2a93b` and a 1 px `#ffffff1f` highlight along its top edge, inset 6 px; other tiles hover to `#161a24`. An 8 px dot with a 2 px `#07080d` ring sits on a tile's top-right corner: red `#e5484d` when an agent there is blocked, green `#4cc38a` when one finished unseen. A space with a shell terminal whose hc `turn` has not changed for 10 min gets a 10 px hollow ring (`#07080d` fill, 1.5 px `#7a8296` border) at the tile's bottom-right corner, offset 3 px past it. Spaces sharing a git repository (the first terminal in the space that has a cwd resolves to the same `git rev-parse --git-common-dir`, resolved on that space's own machine; repositories are keyed by machine, so the same path on two machines is never one repository) are joined by 2 px trunks in the 16 px gutter left of the tiles, at x 8 and x 3 for two overlapping repos (a third gets no lines); the rail also keeps each repository's spaces next to each other in Herdr's own order with `space.move`, the base checkout first. The trunk is `#3a4050`, running from the group's first tile's centre to the last one's and stopping 8 px short when the last is a worktree; each member gets a 2 px stub — straight into the base checkout (or the group's first space), a rounded elbow (`border-left` + `border-bottom`, 8 px bottom-left radius) into each later one — always `#3a4050`; the shown space gets no special colour. The tooltip is "N. name", or "N. name · K idle shells · 15m" when shells are idle. The list scrolls vertically when there are more spaces than fit. Click selects the space (`space.select`); right-click opens Herdr's space menu (`menu` popup, 200 × 260). - **Account avatars** (96 px block, `claude-accounts` with props `{role: "rail"}`): one 40 px avatar per account in list order, except that the focused Claude Code pane's account goes first (on top), packed to the bottom of the block with an 8 px gap and 8 px of bottom padding (the last account sits lowest). Each avatar has three fixed ring slots, 3 px wide, at r 18.5, 14 and 9.5 (4.5 px apart, so 1.5 px of gap; the outermost touches the 40 px edge), filled from the outside: the 5h window in the outer slot, the 7d window in the next, so a ring keeps its size and place whatever the count and fewer windows only leave the inner slots empty (today `windows` always holds 5h and 7d, so the innermost slot stays empty). Each ring draws a full `#c4c8d2` track so the outer edge never changes; the used part is an arc from 12 o'clock clockwise in `#5b9cf5`, `#e5484d` from 90 %. A centre disc of radius 7.5 (`#1a1e28`, hover `#161a24`) holds the account's first letter (10 px semibold): on the focused Claude Code pane's account the disc is filled amber `#f2a93b` with a `#07080d` letter (no disc is amber when no Claude Code pane is focused, or until the read for the pane focused now comes back), else `#eef0f5` on the account new sessions open as (the global default), else `#7a8296`. Each arc is drawn in `arc_to` pieces of at most a quarter turn, since one large arc whose ends nearly meet is painted off-centre. The tooltip is "name · 5h 24% · 7d 11%", with `–` for a window with no usage, ` ↻ HH:MM` (or the weekday) from 90 %, then ` · this pane` on the focused pane's account and ` · new sessions` on the global default. A click opens the account popup. - **Buttons** (84 px block, `tower-rail` with props `{role: "buttons"}`): 32 px + (new space) and settings buttons, bottom-aligned with 12 px bottom padding and an 8 px gap, their 14 px and 15 px icons in `#7a8296`, hovering to a `#161a24` background with `#eef0f5` icons; they run `space.new` and `app.settings`. This block reads no git state. - **Head** (44 px row, drags the window): the shown space's name (Nunito 15 px bold, `#eef0f5`), then, when non-zero, "N need you" with a 6 px `#e5484d` dot and "N working" with a 6 px `#5b9cf5` dot, then "N aircraft" (all three Nunito 13 px, weight 600, `#7a8296`), 20 px side padding and 12 px gaps. The row holds only this title block; the [claude-accounts](https://github.com/lcalmsky/herdr-claude-accounts) mod sits in the rail below the tiles as its account-avatar block (see Rail), shipped here as `mods/claude-accounts/` with the identical files: its popup marks the focused Claude Code agent's account as "this pane", else `default`. Its `RECIPE.md` describes the avatars and popup. - **Runways** (352 px block, 12 px padding): four cards 76 px tall, 8 px apart, radius 12, `#11141c` with a 1 px `#1d212b` hairline. Their height never changes, empty or not. - Label at the left, 16 px in: an 8 px status dot (TOWER's blinks between opacity 1 and 0.25 every 1200 ms while anything waits), the runway name (Nunito 14 px, weight 800, `#eef0f5`) and the count (Geist Mono 12 px, `#7a8296`). - Status dots: TOWER `#e5484d`, RUNWAY `#5b9cf5`, APPROACH `#4cc38a`, TAXI `#7a8296`. - Edge lights: two rows of 64 lamps (2 × 2 px, radius 1) running from 148 px to 16 px before the right edge, 24 px apart, 5 px from the top and 5 px from the bottom (the lower row's top at 69 px), in the runway's status color at `55` alpha, or `aa` on the focused runway. - Threshold keys: a 6 × 48 px block at 132 px from the left, holding four 2 px `#272c37` bars spread top to bottom. - A dashed centre line at half height, from 148 px to 16 px before the right edge: 80 dashes, 16 px long with 12 px gaps, 1 px, `#272c37`. - An empty runway shows "No aircraft" (Nunito 12 px, weight 600, `#7a8296`) at its right end, 16 px in. - The focused runway steps up to `#161a24` with a 1 px `#f2a93b4d` border and a 1 px `#ffffff14` highlight along its top, inset 12 px. - **Aircraft**: a 48 × 28 px side-view plane (nose right) made of three stacked 48 × 28 SVGs: `plane-body.svg` tinted by the runway's status color (amber when focused), then `plane-glass.svg` in `#0b0d14` and `plane-shade.svg` in `#00000055`. 6 px below, an 18 px row holds an 11 px spinner (working only, 900 ms, tinted like the plane) and the session name (Nunito 12.5 px bold, `#eef0f5`, amber when focused, truncated at 200 px). The tooltip is "session · space · lane sub" ("Needs you", "Working", "Done, unseen", "Idle"). Aircraft line up from the left, 152 px into the card and 220 px apart, each 12 px below its runway's top edge. - **Tab bar** (38 px): Herdr's tabs, except an unnamed tab shows its agent's session name (else its space's name) instead of its number. The Files and Changes buttons are drawn only when the layout has `panel` and `panel-body` nodes; `control-tower.json` has neither, so they never show here. The bar scrolls the selected tab into view when the selection or a tab's size changes. The wheel switches one tab per notch: a touchpad swipe or a smoothed notch of about 25 px switches one tab, a longer swipe keeps going a tab per 60 px, at most one every 100 ms; a line-based wheel switches one tab per line event. - **Work area**: padding 8, gap 8. Each pane is a card with radius 10, a 1 px `border` (1 px `accent`, amber, when focused) and Herdr's 30 px pane header. - **Status bar** (28 px): Herdr's workspace status. - **Pulse panel** (380 px, not resizable, drags the window, background `#07080d`, text `#eef0f5`, Geist 13 px). It lists live Claude Code, Codex and Gemini sessions in three groups — "Needs you", "Working", "Done" — read every 3 s by `scan.sh`. - Header, 44 px, 16 px side padding, 8 px gap: the 20 px logo (`logo.svg`), "Pulse" (Geist 15 px, weight 600, `#eef0f5`), then an "N to read" chip (24 px, 8 px padding, radius 6, 6 px gap, `#11141c`, 1 px `#1d212b`, 12 px file-text icon `#a3a9b8`, label Geist 12 px weight 600 `#eef0f5`, tooltip "Open the oldest page (N)", click opens the oldest page). At the right, 12 px apart: three counts, each a 6 px dot then a number in Geist Mono 12 px `#7a8296` — attention `#e5484d`, working `#5b9cf5`, done `#4cc38a`. - Search field: 32 px, 8 px from the panel's left and right edges, 4 px below, 8 px inner padding and gap, radius 8, `#11141c`, 1 px `#1d212b`. A 13 px search icon `#7a8296` and "Type to search" / the query (Geist 12.5 px; placeholder `#7a8296`, query `#eef0f5`). Clicking it gives the panel the keyboard. - Section headers, 40 px, 8 px side padding, 8 px gap: a 6 px group dot, the title (Geist 13 px, weight 600, `#eef0f5`) and the count (Geist Mono 12 px, `#7a8296`). Group colors: Needs you `#e5484d`, Working `#5b9cf5`, Done `#4cc38a`. - Cards: full width, 8 px horizontal and 12 px vertical padding, radius 8, 6 px between the lines inside and 4 px between cards, a 16 px glyph column (Done: 12 px `✓` in `#4cc38a`; Working: 11 px spinner in `#5b9cf5`; a stalled session: an 8 px circle with a 1.5 px `#e5484d` ring; Needs you: an 8 px `#e5484d` dot). A card is `#07080d` and hovers to `#11141c`; the selected card is `#1a1e28` with a 1 px `#f2a93b80` border and an amber title. Its height is 24 px of padding plus its lines plus 6 px between them. - Title line, 20 px: the title (Geist 14 px, weight 600, `#eef0f5`; `#f2a93b` when selected, truncated) and at the right, Geist Mono 12 px `#7a8296` — Done "just now" / "5m ago" / "2h ago", Working the ETA (`~12m left`) or the time in status (`5m`, `2h`), Needs you the time in status, a stall `quiet 12m`. - Meta line, 18 px, 6 px gap: an 18 px kind badge (4 px padding, radius 4, `#11141c`, 1 px `#272c37`, Geist Mono 11 px `#a3a9b8`: `herdr` for herdr-app, `tmux`, `orca`), the place (Geist 12 px, weight 500, `#7a8296`, truncated), key and PR tags (Geist Mono 12 px `#a3a9b8`, each preceded by a `·` in `#3a4050`), and at the right the background count for Working and Done rows ("2 shells · 1 agent", Geist Mono 11 px `#7a8296`). - Needs you cards add the answer: Geist 12 px on 18 px lines in `#a3a9b8`, at most 2 lines (36 px). - Working cards add a "now" line, 18 px: Geist 12 px `#a3a9b8` on a single truncated line; a shell waiting on background work shows "Waiting on background tasks" in `#7a8296`. - Progress line, 16 px, 8 px gap: segments sharing the width with 2 px gaps, each 4 px tall and radius 1 — done `#4cc38a`, now/side `#5b9cf5`, blocked `#e5484d`, left `#272c37`; then "done/total" in Geist Mono 11 px `#7a8296`. The whole line is at 45 % opacity when the checklist data is older than 30 min. - Step list, when expanded: a 1 px `#1d212b` top border, 6 px above and 2 px below, 2 px between steps. Each step is 20 px: a 16 px glyph (11 px `✓` `#4cc38a`, 11 px `!` `#e5484d`, a 9 px spinner `#5b9cf5`, or 11 px `○` `#3a4050`), the label (Geist 12 px: done `#7a8296`, blocked and now/side `#eef0f5`, left `#a3a9b8`) and a note at the right (Geist Mono 11 px `#7a8296`, at most 120 px). The first → shows a 3-step window around the current step (a blocked step is always kept in view) and, when steps are hidden, "N more · → all M"; → again shows the full list. - A page tag under the card: 20 px, 8 px padding, radius 4, 6 px gap, `#11141c`, 1 px `#272c37`, a 12 px file-text icon `#a3a9b8`, the label (Geist 12 px, weight 600, `#a3a9b8`) and `+N` when the row has more than one page. - The selected card, when it is not Done and has a page (a deadhd `pagePath`, else its first page alert), adds a 28 px "Progress page" button: 8 px padding, radius 6, 6 px gap, `#11141c`, 1 px `#272c37`, label Geist 12 px weight 600 `#eef0f5`, and a keycap (18 px tall, 18 px minimum wide, 4 px padding, radius 4, 1 px `#272c37`, Geist Mono 11 px `#a3a9b8`) reading `⇧↩`. - A "N more" row (28 px, 32 px left padding, Geist 12 px weight 600 `#7a8296`) expands the Done group past its first 5 cards. - With no rows the list shows "All quiet for now" — or "No matching sessions" while searching — centred in Geist 13 px weight 600 `#7a8296`. - Key legend, shown only while the panel holds the keyboard: a 1 px `#1d212b` top border, 16 px side padding, 8 px vertical, 6 px between rows, two items per row. Each item has keycaps (18 px tall, 18 px minimum wide, 4 px padding, radius 4, 1 px `#272c37`, `#11141c`, Geist Mono 11 px `#a3a9b8`) then the label (Geist 12 px `#7a8296`), in the order Move (↑ ↓), Open session (↩), Steps (→ ←), Acknowledge (⌫), Oldest reply (Space), Oldest page (Tab), Oldest done (⇧ Space), Back (Esc). - Footer, 28 px, 16 px side padding, 12 px gap, a 1 px `#1d212b` top border: "updated Ns ago" (or "Not updated yet") at the left and "N sessions · N roots" at the right, both Geist Mono 11 px `#7a8296`. - A scan error, or an action notice such as "Marked as seen", adds a strip above the footer: 1 px `#1d212b` top border, 16 px side padding, 4 px vertical, 8 px gap, the message (Geist 12 px; `#e5484d` for an error, `#7a8296` for a notice, truncated) and a 22 px button (8 px padding, radius 6, `#11141c`, 1 px `#272c37`, label Geist 12 px weight 600 `#eef0f5`) reading "Retry" or "Undo". - **Theme** `control-tower`: background/canvas `#0b0d14`, chrome `#07080d`, foreground `#eef0f5`, border `#1d212b`, selected `#1a1e28`, hover `#161a24`, muted `#7a8296`, accent and cursor `#f2a93b`, selection `#26304a`, bright ANSI colors for terminal output. ## How it behaves - **Status → runway**: blocked → TOWER, working → RUNWAY, done → APPROACH, idle → TAXI. On a change the aircraft slides (left and top, 400 ms ease-out) to its new place. On each runway the most recent change comes first, and the same order is handed to Herdr (`setAgentOrder`). - **Focus**: the focused agent's runway steps up as above. That aircraft's plane and session name turn amber `#f2a93b`. Nothing glows, pulses or loops except the working spinner and the TOWER dot while something waits. - **Session name**: the agent's terminal title (Claude Code sets it) without leading symbols; when the title is a path, has `@` or is just the program name, the tab name; else the program name. The tower uses this rule. - **Clicks**: an aircraft focuses its pane (`pane.focus`); resting the pointer on it shows a tooltip with the session name, space name and lane. A rail tile selects its space (`space.select`), a right-click opens Herdr's space menu, and its tooltip names the space (and any idle shells). + runs `space.new`, the gear `app.settings`. The tab bar switches and scrolls as described under Tab bar. - **Rail grouping**: every 30 s the rail asks git (`rev-parse --git-common-dir --show-toplevel`) for every distinct terminal cwd. For a space on another Herdr machine the command runs on that machine (`exec` with `on: `) with a 5 s timeout, and each repository is keyed by machine, so the same path on two machines is never one repository. Once no first terminal cwd is still waiting on a git answer, it reorders spaces with `space.move` so one repository's spaces sit together, base checkout first; each order is tried once (the last attempted order is remembered), and while a first cwd is unanswered the order is left alone. The repository comes from a terminal's cwd — `SpaceInfo.folder` is only where new terminals start, not where they are. - **Pulse poll**: every 3 s it runs `sh /mods/pulse/scan.sh` and reads one JSON object per session line plus a meta line. The script reads Claude Code's session records and transcripts, Codex rollout logs and Gemini chat files, the handoff file a session starts from, the thread-memory folder and goals file when `$HERDR_THREAD_SESSIONS` / `$HERDR_GOALS_FILE` or `~/.config/herdr-shared/scan.json` names them, deadhd state and page alerts, and the session processes' environments; it writes only a ledger and identity cache under `${TMPDIR:-/tmp}/herdr-pulse` (`$DEADHD_STATE_DIR` defaults to `/tmp/deadhd-state`, `$PULSE_PAGES_DIR` to `~/.pulse/pages`). - **Pulse groups**: a waiting session is Needs you; a busy session is Working unless it has no background work and nothing meaningful for 10 minutes, which makes it a stall under Needs you; a shell is Needs you when its checklist has a blocked step; idle is Done. Needs you and Working sort oldest first, Done newest first. Done sessions leave the list once seen or after 12 h, and only the first 5 are shown until "N more" is clicked. A stall can be snoozed for 10 minutes. The Need-you answer is the blocked step's ask, the last answer, "Waiting for permission approval" when the waiting reason is a permission prompt, or "Waiting for your reply"; a stall explains how long it has been quiet. - **Pulse opening**: a click on a card, or ↩, finds the Herdr terminal by the session's foreground pid, else by its terminal id, and focuses its pane; otherwise it switches a tmux client (`switch-client`, `select-window`, `select-pane`); otherwise it runs the Orca CLI's `terminal switch --terminal --json` and then `open -a Orca` (when the switch succeeds but `open -a Orca` fails it shows "Switched in Orca, but couldn't bring it forward"). When none matches it shows "Not in Herdr, tmux or Orca". A background Claude Code session (`claude-bg`) with an attached `claude attach` pane focuses that pane; without one it opens `claude attach <8-char id>` in a pane split right of the focused pane, so `claude` runs there (a second click within 15 s does not open another; when the focused pane belongs to a space on another Herdr machine it shows "Focus a pane on this computer to attach" instead, since attach would run there). - **Pulse pages**: a page tag opens its URL with `open`; once it opens, the alert files behind it are deleted with `rm -f` and the tag disappears. ⇧↩ and the Progress page button open the row's page; Tab opens the oldest page in the meta list. - **Pulse memory**: seen sessions are kept in localStorage `"pulse.seen"`; search and snooze are in memory. Search ignores case and accents and matches the title, place, cwd's last component, session name, and key/PR tags. - **Under `herdr-app check`**: `checking()` is true and every mod only renders. No program runs (`scan.sh`, `cca`, `git` and the Orca CLI included) and no timer starts, so the check has no side effects. ### Pulse keys The panel takes the keyboard with ctrl-alt-p or by a click inside it; the rest work while it holds focus. | Key | Action | | --- | --- | | ctrl-alt-p | Global key: `"ctrl-alt-p": "pulse.toggle"` in the `global` section of `keys.json`. Gives Pulse the keyboard, or hands it back with `pane.go left` when it already has it. | | ↑ / ↓ | Move the selection one card, wrapping at either end. | | ⌥↑ / ⌥↓ | Jump to the first / last card. | | → / ← | Step disclosure: collapsed → the 3-step window → the full list (← reverses). On a card without steps, → expands all Done cards. | | ⌥→ / ⌥← | Jump straight to the full step list / back to collapsed. | | ↩ | Open the selected session. | | ⇧↩ | Open the selected row's page. | | Space | Open the session that has waited longest for a reply; pressing again cycles through them. Stalls are skipped. | | ⇧Space | Open the oldest finished session and mark it seen, with an Undo button for 6 s. | | Tab | Open the oldest page. | | ⌫ | Delete the last search character; with no search, acknowledge the selected card: hide a Done card, or snooze a stall for 10 min. | | ⌥⌫ / ⌘⌫ | While searching, delete the last word / clear the whole search. | | Esc | Clear the search, then the selection, then hand the keyboard back with `pane.go left`. | | any character | Type into the search. | Moving the selection with ↑/↓, ⌥↑/⌥↓ or Space scrolls the list so the selected row is visible. One click on a card selects it and opens its session. Opening an Orca session runs `orca terminal switch`, then `open -a Orca`; a switch that succeeds followed by a failed `open -a Orca` shows "Switched in Orca, but couldn't bring it forward". ## Built from - `layouts/control-tower.json`: root `row` (theme `control-tower`, background `canvas`, titlebar none, traffic_lights [12, 16], terminal_padding [14, 12], 1 px `border` dividers): - `rail` column (px 64, not resizable, `window_drag`, background `chrome`) with three blocks: `rail-spaces` (no size, `tower-rail`), `rail-accounts` (px 96, `claude-accounts` with props `{role: "rail"}`) and `rail-buttons` (px 84, `tower-rail` with props `{role: "buttons"}`); - `work` column (not resizable): `tower-head` row (px 44, `window_drag`) with `tower-title` (`tower` with props `{role: "head"}`, fills), `tower-lanes` (px 352, `tower`), `tabs` (px 38, `tower-tabs`, no `window_drag`), `work-body` row (padding 8, gap 8) with `main` (`{tab: "active", pane: {header: {content: {mod: "pane"}, reveal: "always", height: 30, position: "top"}, background: "background", border 1 `border`, focus 1 `accent`, radius 10, gap 8, lone: true}}`), and `status` (px 28, the shipped `workspace-status`); - `pulse` block (px 380, not resizable, `window_drag`, background `chrome`) with `pulse`. - `themes/control-tower.json`: the theme above. - `mods/tower/`: `props().role === "head"` draws the head, anything else the runways. The aircraft is `plane-body.svg` (the body, tinted with `text_color`) under `plane-glass.svg` (`#0b0d14`) and `plane-shade.svg` (`#00000055`). `fonts/` holds Nunito SemiBold and Bold (OFL), picked up automatically and used through `font_family("Nunito")` for the head, runway names and aircraft names. - `mods/tower-rail/`: the rail's tiles (the default role, `role: "spaces"`): one 32 px tile per space with its first letter, the blocked/done dot, the idle-shell ring, git-repo trunk lines and nothing else; with props `{role: "buttons"}` it draws only the new-space and settings buttons and reads no git state. It bundles no fonts; the letter uses the window font. Every 30 s it resolves the git common directory of each terminal cwd and moves the spaces of one repository together with `space.move` (base checkout first), trying each order once and holding off while a space's first cwd is unanswered; for a space on another Herdr machine the command runs on that machine through `exec` (`on: `, 5 s timeout) and repositories are keyed by machine, and the tile list scrolls vertically when there are more spaces than fit. - `mods/pulse/`: the Pulse board, its `logo.svg`, and `scan.sh`. It uses Geist for text and Geist Mono for numbers. - `mods/claude-accounts/`: an identical copy of the [claude-accounts](https://github.com/lcalmsky/herdr-claude-accounts) mod (`main.js`, `mod.json`, `cca`, `usage-tap.sh`, `usage-api.mjs`, `codex-usage.mjs`, `models.mjs`, `fonts/`), which the layout places as the rail's account block (`{role: "rail"}`); its ring avatars are drawn with `PathBuilder.stroke` and `window.paint_path`, and a click opens the account popup. Its own RECIPE describes it. - `mods/tower-tabs/`: Herdr's shipped `tabs` (0.1.12), modified: an unnamed tab shows the lead agent's terminal title, else its space's name; the bar's left padding is a fixed 10 px; the Files and Changes buttons need `panel` and `panel-body` nodes (this layout has none); the wheel switches a tab per 25 px notch (one per 60 px on a longer swipe, at most one every 100 ms, one per line event for a line-based wheel); and the bar scrolls the selected tab into view when the selection or a tab's size changes. Apache-2.0, with its LICENSE. - `herdr` functions: `agents`, `spaces`, `focused`, `run`, `exec`, `appHome`, `setAgentOrder`, `props`, `openOverlay`, `closeOverlay`, `terminals`, `panes`, `nextCommand`, `theme`, `window`, `shared`, `layout`. - Commands: `pane.focus`, `pane.go`, `space.select`, `space.new`, `space.move`, `app.settings`, `pulse.toggle`, and the tab bar's `tab.*`, `layout.show/hide/select`, `window.*`. - Shipped mods and icons: `pane`, `workspace-status`, `menu`, `new-menu`, and icons from `mods/workspace-chrome/` (spinner, plus, settings, search, file-text), `mods/pane/`, `mods/files/`, `mods/changes/`, `mods/tower-tabs/` (window buttons). - Programs: `tower` runs none; `tower-rail` runs `git -C rev-parse --path-format=absolute --git-common-dir --show-toplevel` for each terminal cwd every 30 s, and on another Herdr machine's space the same command runs there through `exec` (`on: `, 5 s timeout) (the buttons role reads no git state); the rail's account block runs `cca` from the claude-accounts mod, which runs `node` (`models.mjs`, `usage-api.mjs`, `codex-usage.mjs`) and `security`, reads `~/.codex` and `~/.codex-accounts`, and asks Claude's usage endpoint at most every 5 minutes. `pulse` runs `sh mods/pulse/scan.sh` every 3 s; the script runs `python3`, `ps` (`eww` and `-axww`) and `lsof`, and reads `sessions/*.json`, `projects/*/.jsonl`, Codex rollout logs under `~/.codex/sessions`, Gemini chat files under `~/.gemini`, the handoff file, the optional thread-memory folder and goals file when configured, deadhd state, page alerts and process environments. `pulse` also runs `tmux`, the Orca CLI at `/Applications/Orca.app/Contents/Resources/bin/orca`, `open` (page URLs and `open -a Orca`) and `rm -f` on page alert files. No mod other than `cca`'s usage refresh makes network calls. ## Watch out - `agent.focused` isn't enough to find the selection; also compare `focused().terminal` / `focused().agent` with the agent's address. - Only opacity, width, height, left and top animate. Aircraft keep a stable element id per agent (`slot-
`) and are drawn in address order so they slide instead of jumping. - Runways keep their height when empty on purpose: collapsing them would shift every runway below on each status change and bury the one move that matters. - A block doesn't report its width, so lanes are fixed px and the runway clips. The dashes are a fixed count (80) that covers a wide window. On a 1600 px window the work column is about 1154 px (1600 − 64 − 380 − 2 dividers), which fits four aircraft on a runway; more run off the right edge. - The runway block is sized for four 76 px runways with 8 px gaps (4 × 76 + 3 × 8 + 24 padding = 352). Changing the runway height means changing the layout's px too. - The head has no timer of its own; the runways and the rail notify every 30 s so the rail's idle rings and tooltips advance. - The rail's idle ring has no last-activity time from hc: its 10 min count starts when the mod last saw that terminal's `turn` change, so after a reload nothing shows for 10 min. - The rail reads a space's first terminal cwd, never `SpaceInfo.folder`; a space whose terminals have no cwd is grouped only under its own id. - The rail's trunk lanes are fixed at x 8 and x 3 (`LANES = [8, 3]`); a third repository whose spaces overlap the first two gets no lines, on purpose. - The rail's account block is 96 px tall: two 40 px avatars with an 8 px gap and 8 px bottom padding. Each further account needs 48 px more (40 + 8) in `layouts/control-tower.json`. - GPUI colors accept `#rrggbbaa`; the focused runway's amber hairline (`#f2a93b4d`), the selected Pulse card's border (`#f2a93b80`) and the shade plane layer use it. - Pulse's `scan.sh` lists Claude Code CLI sessions (`entrypoint === "cli"`), plus Codex and Gemini sessions started as native CLI processes; other agents still appear on the tower's runways but not in Pulse. ## Done when - `herdr-app check mods/tower`, `mods/tower-rail`, `mods/tower-tabs`, `mods/pulse` and `mods/claude-accounts` all pass, and `layout.switch {name: "control-tower"}` shows the rail, head, four runways, tabs, panes and the Pulse panel with no errors in `herdr-app status`. - Starting an agent puts an aircraft on RUNWAY with a spinner; when it waits for permission the aircraft slides to TOWER with a red plane; when it finishes unfocused it slides to APPROACH. No runway changes height. - Clicking an aircraft focuses its pane; that aircraft turns amber and its runway steps up while the previous one returns to `#11141c`. - The rail lists each space as a tile; clicking a tile selects that space, a right-click opens its menu, and the blocked/done dots follow the agents. - The Pulse panel shows the session within 3 s, grouped by needs-you / working / done; ctrl-alt-p gives it the keyboard and Space opens the session waiting longest. - An unnamed tab shows the session name (or, with no usable title, the space name) instead of a number. - The rail shows one `claude-accounts` ring avatar per account at the bottom, above the + / settings buttons; clicking one opens that mod's popup (its RECIPE has the checks for the rows, the resume section and the amber headroom dot).