# Sub-agent Accordion The sub-agents of the shown tab (terminals an agent started with `hc run`, on this computer or on another machine) sit in a card to the right of the terminals as a horizontal accordion. Each one is a thin vertical strip: its status, its program icon and its name written bottom to top. Click a strip and that sub-agent's live terminal opens as a 440px card beside the strips, with its own colors and keyboard; opening one closes the other, and clicking the open strip closes it again. With no sub-agents the card is gone. ![Sub-agent Accordion](preview.png) ## What you see - **The strip card:** one block at the right end of the row that holds the terminal cards, level with them (same top and bottom edges, 10px radius, 1px `border`), `chrome` background. The layout's top bar and status bar run across above and below it, unchanged. Its width is 28px per sub-agent; with none it is 0px wide and draws nothing. - **Strips**, left to right in core order (`terminals()`), each 28px wide and full height, 8px top and bottom padding: - top (36px): the status in a 14px-high row (see below), then the program's 14px icon from the app's program table (`program.icon`; tinted with `foreground` when `program.tint`); - middle, centered on what's left: the name rotated -90° (reads bottom to top), 12px, weight 500, `muted` (`foreground` when open). A remote sub-agent's name ends with ` · ` (e.g. `s6-files · mini`). Names longer than 48 characters end in `…`. The name is `name`, else `template`, else `program.name`, else the address; - bottom (36px): empty, or the open strip's Keep button `↗` (12px, `muted`, `foreground` on hover); - background `chrome`, `selected` when open, `hover` under the pointer; tooltip: ` (
) · ` with the words `working`, `needs you`, `finished`, `idle`; - a blocked sub-agent's strip has a 2px `blocked` left edge. - **The open sub-agent:** a separate block just left of the strip card, 440px wide, 10px radius, 1px `border`, showing that sub-agent's terminal live (the same view as a pane: its colors, formatting, cursor and typing). ![Collapsed: four sub-agents, one per status](collapsed.png) ## How it behaves - Status per sub-agent, from its OSC 7501 report (`agents()` when listed there, else the terminal's own `status`; `error` counts as blocked): - **working**: a braille spinner `⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏` in `working`, 12px, animated natively (`.frames`, 90ms); - **blocked**: a 14px badge with 4px corners, `!` (10.5px, bold) in `blocked` on a 15% `blocked` tint (`blocked + "26"`), plus the 2px left edge; - **done**: a 7px dot in `done`; - **idle**: a 7px ring (1.5px border) in `idle`; - a plain program without a report: a 7px dot in `unknown`. - Click a closed strip: its terminal block opens and any other open one closes. Click the open strip: it closes. A sub-agent that ends while open just goes and its block is removed; nothing opens instead. New sub-agents always arrive closed. - Click into the open terminal to type in it; it takes the keyboard like any terminal. - **Keep** (`↗` at the bottom of the open strip) runs `terminal.keep`: the sub-agent gets a pane in its tab, and from then on it leaves the accordion (it is in the tab itself). The click does not also close the strip (it stops propagation). - The open one is remembered per mod copy (`localStorage` key `open`), so a reload, layout switch or restart reopens it while it lives. - The open address is also published as shared state `subagent-accordion.open` (null when none), so an agents list can highlight it. It is written only when it changes. - Switching tab or space shows that tab's sub-agents; the card resizes to fit them. ## Built from - **One mod**, `mods/subagent-accordion/` with `main.js` and `mod.json` = `{ "place": "right", "size": 28, "title": "Sub-agents" }`. No props, no `keys.json`, no `layouts/` folder. - **A block in the person's own layout** (a clone, never a shipped one): `{ "id": "subagents", "type": "block", "content": { "mod": "subagent-accordion" }, "size": { "px": 28 }, "radius": 10, "border": { "width": 1, "color": "border" } }` as the last child of the row that holds the `{ "tab": "active" }` block. In a `main` clone that is `work-body` (`"padding": 8, "gap": 8`, holding `main` and the Files/Changes `panel`), so the card lines up with the terminal cards. If the tab block sits directly in a column, wrap it in such a row first. Right before it, in the same row, put the hidden terminal block described next. - **Which sub-agents:** live terminals (`state === "live"`) with a `parent`, without a pane of their own, whose nearest ancestor with a pane is in `focused().tab`. The parent chain is walked up to 32 steps, so a sub-agent of a sub-agent counts. Addresses are taken as the app gives them: `t7` here, `mini/t7` on machine `mini`; a remote terminal's `parent` written without a machine is read on the child's machine. - **The open terminal block:** a hidden block the layout declares just before the card: `{ "id": "subagent-accordion-terminal", "type": "block", "content": { "agent": "focused" }, "size": { "px": 440 }, "radius": 10, "border": { "width": 1, "color": "border" }, "hidden": true }`. Opening a strip runs `layout.show { id }` then `agent.focus { terminal }`; closing runs `layout.hide { id }`. Without that block in the layout the mod still lists strips but opens nothing. The layout tree is never rewritten. - **The card's width:** `run("layout.resize", { id, px: count × 28 })` on its own block (found in `layout()` by `content.mod`), sent only when that number changes and only if the block has a `px` size. - **The rotated title:** gpui-kit has no rotate, transform or writing-mode for text, but GPUI's SVG renderer draws `` with the system fonts. Each distinct title becomes a 16px-wide SVG, height `ceil(len × 12 × 0.62) + 8`, `` (text XML-escaped), written once with `fs/promises` `mkdir` + `writeFile` to `mods/subagent-accordion/.labels/.svg` (`crypto` `createHash`) and drawn with `svg(path)` so `text_color` tints it. - **`herdr` functions:** `terminals()` (address, parent, state, status, name, template, program), `agents()` (status), `panes()` (terminal → tab), `focused().tab`, `layout()`, `theme()`, `appHome()`, `shared` / `setShared`, `run("layout.show")`, `run("layout.hide")`, `run("agent.focus")`, `run("layout.resize")`, `run("terminal.keep")`. Elements: `div`, `svg`, `image` from `gpui-kit`, `h_flex`, `v_flex` from `gpui-base`. - **What it touches:** it runs no programs (no `exec`, no `hc`), reads no screens and reaches no network. It writes title SVGs under its own folder (`.labels/`) and shows/hides one layout block. Say so before adding it. ## Watch out - Checked with `herdr-app 0.1.13`; follow the installed `herdr.d.ts` and `gpui-kit.d.ts` if they differ. - The terminal block needs a layout you can edit (`layout.clone` a shipped one), since it adds the hidden block to the layout file. - Never `layout.set` from this mod: the app collapses single-child columns on save (Herdr's `panel` column around `panel-body` disappears) and `layout()` is lossy, which broke the top bar's Graph/Linear/GitHub toggles and stretched their panels. Use `layout.show` / `layout.hide` / `layout.resize` only. - The `.labels` folder must be hidden (leading dot): the app reloads a mod for any other file written under its folder. - A strip's title is blank for the instant before its SVG is written; don't fall back to stacked letters. - Send `layout.resize` only when the wanted width changes, never on every render: otherwise a person dragging the divider fights the mod. - Copying a mod with `"place": "right"` into `mods/` makes the app dock one copy at the root of the shown layout the first time (beside the whole window, top bar included). Put the block in the row described above instead and remove the auto-docked one. - No `setAgentOrder`: pane-less sub-agents aren't in `agents()`, so calling it would only override the agents list's own order. - While the open terminal block has the keyboard, implicit `pane.split` / `pane.close` / `pane.zoom` and `terminal.show` fail: it is a layout block, not a pane of the tab. Click a pane first. - Many sub-agents widen the card by 28px each; there is no scrolling. Only one sub-agent is open at a time. ## Done when - `herdr-app check ~/.config/herdr-app/mods/subagent-accordion` passes. - With no sub-agents in the shown tab, the card takes no room. - `hc run --bg --no-notify --name sa-test -- sh -c "printf '\033]7501;state=working\007'; sleep 600"` started from an agent's terminal makes a 28px strip with a spinner and the vertical name `sa-test` appear while that agent's tab is shown, level with the terminal cards, the title reading bottom to top and centered on the strip. - `state=blocked`, `done`, `idle` show the `!` badge with the red left edge, the filled dot and the ring. - The same from an agent on another machine shows a strip named ` · `. - Clicking a strip opens a 440px live terminal block left of the strips (real colors, typing works) and closes any other; clicking it again removes the block; killing the open sub-agent removes it too. - `↗` gives the open sub-agent a pane in its tab, and its strip leaves the accordion. - Switching layouts away and back reopens the sub-agent that was open.