# herdr-composer A message bar under the terminal. The person types to the focused agent in one field that is theirs: the text survives switching agents and restarting Herdr, a message sent while the agent works waits for its turn and goes out on its own, files and images are dropped, picked or pasted in, and everything sent can be found again (and starred) in a History | Favourites panel. The terminal underneath only shows. ![herdr-composer](preview.png) It is a layout (a clone of `main`, Herdr 0.1.16) plus one mod. It descends from the `ovis-composer` mod of this repo; the UX is inspired by Ovis (devswha/ovis). ## What you see The window is the `main` layout with one block added. Left to right, top to bottom: - **Sidebar**, 268 px, `chrome` background: brand row (46 px), the Spaces list and the Agents list (equal weight, 90 px minimum), the footer (69 px). - **Work column** (resizable): tabs (42 px), then the body (8 px padding, 8 px gap): the terminal pane of the active tab and, on the right, a 368 px panel (280-900 px) with Files and Changes; then **the composer block**; then the status bar (28 px). - **The composer block** starts at 150 px layout height (120-520) and is as tall as its content (see Watch out); its content sits at the bottom edge, 8 px padding, 6 px gap. Top to bottom, only what applies is drawn: 1. the suggestion menu (rounded 10, `popover` background, a list 118 px high, groups in 10 px `dim` type, one row per command or file); 2. the queue: one row per waiting message (a 7 px colored dot, the text, a state label, buttons); 3. the question about an image for a program that may not take it; 4. a notice line (11.5 px; `dim`, or `blocked` red for problems); 5. **the card** (rounded 12, 1 px `border`, `raised` background): attachment tiles (44 px high: 36 px thumbnail or extension, name, size or reason, "Ponów", x), the field (`background`, rounded 8, 13 px, 1 to 10 rows), and a row of controls: three 28 px round buttons `+`, a clock, a star; a 1x18 px divider; **the dock** (flexible, 28 px high, scrolls sideways: one 28 px button per saved text, rounded 8, 12 px; a send button on `chrome`, an insert button with a 1 px dashed `border` and a `✎` prefix; empty: "Prawy klik w Ulubionych → Przypnij do docka" in `dim`); the agent pill (rounded 12: a 7 px status dot, the tab's name, the status word, a paperclip and the count when files are attached); and a 32 px round button, a white arrow to send, or a white square (Stop) when the field is empty and the agent works; 6. the strip: `space · folder · branch` left (11 px, `dim`), `N / 20000` right (red `Limit 20000 znaków · N za dużo` when over). - **The panel** (Ctrl+R or the clock) covers the whole block (6 px inset, rounded 12, `popover` background): the header (tabs "Historia N" and "Ulubione N", a 30 px search field with a magnifier, a 28 px close x), the list (rows 56 px: the text in two lines with the match lit, a line `DD.MM HH:MM · space · tab`, a star), the footer with the keys. While it is open a block lower than 320 px is made 360 px tall and goes back when it closes. - **The preview** of an image (click a thumbnail): a dark scrim over the block, the image, `name · size · Esc zamyka`. Polish is the language of every text of the mod. ## How it behaves **Status of the agent** (pill dot and word): working "pracuje", blocked "czeka na Ciebie", done "skończył", idle "gotowy" (the dot takes the theme color of the status). **Focus follows the click.** The composer never takes the keyboard on its own: the field has it after a click on it or `ctrl-shift-space`; a click in a terminal gives the keys to that terminal. A focus on a terminal that is not an agent: the field is replaced by "Ten terminal nie jest agentem. Wybierz agenta z listy, aby pisać." and the draft is kept. **Keys in the field:** Enter sends (the message is trimmed; empty is ignored), Shift+Enter a new line, Ctrl+Enter sends now whatever the status, Alt+Enter queues it held ("Wstrzymana — wyślij ręcznie"), Ctrl+R opens the panel, Esc closes the menu or the panel and otherwise, with an empty field and a working agent, stops the agent (`hc interrupt`; the queue is held and nothing goes out on its own). Up/Down/Tab move and accept in the suggestion menu; without a menu Up/Down move the cursor between lines. **Sending.** Idle or done: out at once ("Wysłano do terminala."). Blocked: out at once with `--force` (an answer), ahead of the queue. Working: into the queue ("Następna tura"). When the turn ends (working or blocked, then idle or done) the first queued message counts down "Wysyłam za 3 s" (button "Anuluj" holds it) and goes out; the next waits for the next turn. One message per turn. A message that goes while another is queued or counting waits at the end of the queue. Queue rows: "Wyślij teraz" (held), "Ponów" (an unconfirmed one), "Edytuj" (back into the field at the caret), "Usuń". After a restart a message that was on the wire is "Nie potwierdzono" and is never sent again on its own. **Drafts.** Per agent (the key is the address, `t2`), written 500 ms after the last change and at once when the agent changes; text, caret, attachments. The identity of the terminal (`created_ms` from `hc get`) is stored with it: when the address now belongs to another terminal the draft comes back with "Szkic z poprzedniej sesji agenta" and the whole queue is held. **Suggestions.** `/` at the start of a line: the built-in commands of the agent (`claude-code`, `codex`, ...), the project's `.claude/commands/*.md` and `.claude/skills/*/SKILL.md`, ranked by use; `@`: the project's files (`git ls-files`). **Attachments.** One pipeline for a drop, the `+` button (a file dialog) and Ctrl+V (an image or copied files; text pastes as text): checked (32 MiB a file, 100 a message, no folders), a tile "dodawanie...", `hc put `, then ready and `@path` goes into the text - the path the agent sees, in quotes when it has a space. Pasted images are saved in `data/herdr-composer/paste/` (removed after 7 days). An image for a program other than `claude-code`, `codex`, `gemini`, `opencode` asks first ("Anuluj" / "Wyślij mimo to"). **History and favourites.** Every message that `hc send` accepted is stored (500, newest first, any space or agent). In the panel: type to search (case-insensitive, Polish letters too), Up/Down, Enter inserts at the caret the field had when the panel opened and sends nothing, Tab switches tab, Ctrl+D stars a row at once, a right click opens a menu (Wstaw, Dodaj do ulubionych / Usuń z ulubionych; in Favourites also Przypnij do docka / Odepnij z docka), Esc or the x closes. The star next to the field stars the text in it (100 favourites); a right click on it pins the text to the dock. **Dock.** A row of buttons in the bar, one dock for every agent (30 at most). A click on a send button sends its text the way Enter does (queue, countdown, `--force` when blocked) and leaves the field, the draft and the files alone; an insert button puts its text at the caret. A right click on a button: Zmień nazwę (in place: Enter keeps, Esc drops; an empty name falls back to the first 15 characters + "…"), Tylko wstawiaj / Wysyłaj od razu, Przesuń w lewo / w prawo, Usuń z docka. Without an agent the buttons are dimmed. ## Built from **Layout** `layouts/herdr-composer.json`, a clone of `main` (`cloned_from` 0.1.16), `canvas` background, no title bar, 1 px `border` dividers. Tree: `root` (row) > `sidebar` (column, 268 px, 44-480, `chrome`; `brand` workspace-chrome 46 px, `sidebar-lists` with `spaces` and `agents`, `sidebar-footer` workspace-chrome `{footer: true}` 69 px) and `work` (column, `resizable: true`; `tabs` 42 px, `work-body` row with `main` and `panel` (368 px, 280-900; a stack of `files` and `changes`), `composer`, `status` workspace-status 28 px). The block `composer`: `content: {mod: "herdr-composer"}`, `size: {px: 150}`, `min: 120`, `max: 520`, a `focus` border in `accent`. **Mod** `mods/herdr-composer/` (`mod.json`: `place: none`, `focusable: true`): `main.js` (the view), `state.js` (drafts, attachments, queue; pure), `delivery.js` (sending, the gate, countdown rules), `storage.js` (the shared store, migration from `ovis-composer.*`), `history.js`, `attachments.js`, `clipboard.js`, `suggest.js`, `catalog.js`, `keys.js`, `dock.js` (the dock and its menus; pure), `view.js` (helpers), `panel.js` (the panel and the preview). The pure modules import nothing from Herdr and are tested with Node (`npm test`). **Herdr API:** `agents`, `panes`, `focused`, `theme`, `settings` (`zoom`), `appHome`, `shared`/`setShared` (the store: `herdr-composer.history`, `.favorites`, `.usage`, `.userMin`, `.dock`, `.draft:
`, `.queue:
`), `notify` (toast, only for a failed send or `hc` call), `nextCommand`, `run("layout.resize", {id: "composer", px})`, `cx.bind_keys` in the context `herdr-composer > Input` (up, down, tab, ctrl-r, ctrl-enter, alt-enter, escape), `fs/promises` (the paste folder), gpui-kit and gpui-base (`v_flex`, `h_flex`, `Textarea`, `Input`, `v_virtual_list`, `Scrollbar`, `image`, `on_size_change`, `on_drop`, the `paste_other` event of the textarea). **`keys.json`:** `global` `ctrl-shift-space` -> `herdr-composer.focus`. **Programs it runs - say this before installing:** - `powershell -NoProfile -STA -Command ...` (`exec`): reads the clipboard (files, an image saved as PNG), shows the file dialog, measures the files dropped or picked. Every path goes in as Base64 of UTF-8, never as text of the script. - `hc` (herdr-core): `hc send --json [--force] -- `, `hc put --json`, `hc get --json`, `hc interrupt --json`. - `git ls-files` and, for the `/` menu, `sh` or `powershell` reading `.claude/commands/*.md` and `.claude/skills/*/SKILL.md` in the agent's folder. **Files outside its own folder:** the files the person drops, picks or copies (to attach them), the agent's project folder (the lists above), `data/herdr-composer/paste/`. It makes no network request. **Art:** none; the glyphs `+`, a clock, a star, `x`, a magnifier, a paperclip are text. ## Watch out - `hc send` reads a message that starts with `-` as an option unless the text is after `--`. Always send `["send", "--json", terminal, "--", text]`. - `--force` only for the person's own Enter to a blocked agent, never from the queue. - The block reports its size in logical pixels (layout px times `settings().zoom`); `layout.resize` wants layout px. Divide by the zoom or the block grows by the zoom factor. - The block's height: the content's, floored at the height the person dragged the border to (`herdr-composer.userMin`), 120-520, resized after 120 ms and only for a difference over 4 px; the panel pauses it. - Row handlers cannot live inside a `v_virtual_list` renderer: a row click uses `on_item_click`, so the star in a panel row is a sign; Ctrl+D or a right click toggle it. - `image()` draws only files inside the app's folder (give it the path relative to `appHome()`): thumbnails exist for pasted images; an image from elsewhere gets a tile with its extension and no preview. - The textarea binds the arrows and Tab and eats them; the composer binds the same keys itself in `herdr-composer > Input`. An open panel takes them first, whoever has the keyboard. - Whether Ctrl+Z undoes an insert from the panel is not verified; the notice does not promise it. - A mod copy is loaded once: after an update Herdr must see changed files (`install.cmd` copies them, so it reloads the mod). - Windows only: the clipboard, the `+` dialog and the file sizes use PowerShell. - Limits: 20 000 characters a message, 32 MiB a file, 100 files a message, history 500, favourites 100, the dock 30 buttons, the menu shows 20 rows. - The layout is a clone: it keeps the look of `main` as of 0.1.16 and does not follow later changes of `main`. - Data kept under `ovis-composer.*` by the earlier name is read when the new key is empty and written under `herdr-composer.*`; the old keys stay. ## Done when - `herdr-app check mods/herdr-composer` passes and `herdr-app status` shows no errors with the layout `herdr-composer` shown. - Typing in the field, switching to another agent and back, restarting Herdr: the text and the caret are back for each agent. - Enter to an idle agent sends; to a working one queues, and after the turn a 3-second countdown with "Anuluj" precedes the send; Stop empties nothing but holds the queue. - Enter to a blocked agent sends at once. - A message starting with `- ` or `--help` is delivered as text. - Ctrl+V of a screenshot gives a tile and an `@path`; the agent can read the image. - Ctrl+R opens the panel with the sent messages; search lights the match; Enter inserts at the caret and sends nothing; Esc closes it and the block returns to its height. - Ctrl+Shift+Space focuses the field; clicking a terminal gives that terminal the keys. - A right click on a Favourites row pins it to the dock; a click on the button sends it and leaves the draft; a right click on the button renames, moves, switches the mode and removes it; the dock survives a reload. - `npm test` passes.