202 lines
13 KiB
Markdown
202 lines
13 KiB
Markdown
# 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, `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 (a green check on the send button for 1.5 s). 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`, `profiles.js` (agent profiles), `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-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`; the star in a panel row is found by where `on_mouse_down` on the list landed (STAR_ZONE, right edge). Ctrl+D or a right click toggle it too.
|
|
- `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.
|