docs: RECIPE.md of the herdr-composer package
Co-Authored-By: Ovis Fast (Claude) <[email protected]>
This commit is contained in:
1 parent
7ec0c20989
commit
cfd9ffe943
1 file changed
+186
@@ -0,0 +1,186 @@
|
||||
# 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 flexible gap; 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 <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 or a right click stars a row, Esc or the x closes. The
|
||||
star next to the field stars the text in it (100 favourites).
|
||||
|
||||
## 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`,
|
||||
`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`, `.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`, 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 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.
|
||||
- `npm test` passes.
|
||||
Reference in new issue
Block a user