13 KiB
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.
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,
chromebackground: 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:
- the suggestion menu (rounded 10,
popoverbackground, a list 118 px high, groups in 10 pxdimtype, one row per command or file); - the queue: one row per waiting message (a 7 px colored dot, the text, a state label, buttons);
- the question about an image for a program that may not take it;
- a notice line (11.5 px;
dim, orblockedred for problems); - the card (rounded 12, 1 px
border,raisedbackground): 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 onchrome, an insert button with a 1 px dashedborderand a✎prefix; empty: "Prawy klik w Ulubionych → Przypnij do docka" indim); 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; - the strip:
space · folder · branchleft (11 px,dim),N / 20000right (redLimit 20000 znaków · N za dużowhen over).
- the suggestion menu (rounded 10,
- The panel (Ctrl+R or the clock) covers the whole block (6 px inset, rounded 12,
popoverbackground): 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 lineDD.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 <agent> <file>, 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:<address>, .queue:<address>), 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] <terminal> -- <text>,hc put <terminal> <file> --json,hc get <terminal> --json,hc interrupt <terminal> --json.git ls-filesand, for the/menu,shorpowershellreading.claude/commands/*.mdand.claude/skills/*/SKILL.mdin 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 sendreads a message that starts with-as an option unless the text is after--. Always send["send", "--json", terminal, "--", text].--forceonly 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.resizewants 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_listrenderer: a row click useson_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 toappHome()): 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.cmdcopies 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
mainas of 0.1.16 and does not follow later changes ofmain. - Data kept under
ovis-composer.*by the earlier name is read when the new key is empty and written underherdr-composer.*; the old keys stay.
Done when
herdr-app check mods/herdr-composerpasses andherdr-app statusshows no errors with the layoutherdr-composershown.- 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--helpis 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 testpasses.
