Pouch — store instructions for LLMs while they work in Herdr

A Herdr plugin for stashing prompts before an agent needs them, and inserting them when it is ready.

Queue the next three instructions while the agent is still working, then hand them over one keypress at a time. Text is typed into the input, never submitted — you always press Enter yourself.

┌ 1 👜 ┬ 2 ┬ + ─────────────────────────────────────────────────────────────┐
│ > implement the retry logic │

Requires Herdr 0.7+ and Node 22.6+ or Bun . No build step, no clone.

herdr plugin install AltanS/herdr-pouch
herdr plugin action invoke setup --plugin herdr.pouch

Expected setup output:

✓ plugin installed from GitHub, nothing to link
✓ cli installed ~/.local/bin/herdr-pouch
✓ keys prefix+shift+o, prefix+shift+i, prefix+shift+a bound
✓ keys work prefix+shift+o, prefix+shift+i, prefix+shift+a reach Pouch

✓ did it. · nothing to do. ! needs you, with the remedy on the same line. Re-running setup is safe, and it is how you repair an install.

Setup writes one marked block to ~/.config/herdr/config.toml, between # pouch:begin keybindings and # pouch:end keybindings. Anything outside those markers is yours, and is never rewritten — a chord you already use is reported and left alone. Uninstall removes exactly that block. Setup also keeps a backup at ~/.config/herdr/config.toml.pouch-backup, and uninstall leaves it there.

setup --no-keys skips the config entirely, so you can bind herdr.pouch.<action> yourself.

Check it worked: herdr-pouch add "run the tests" in any pane. The pane wears a 👜, and prefix+shift+O opens the pouch. Until a pouch holds a message, Pouch shows nothing — that is normal, not a failed load.

herdr plugin action invoke update --plugin herdr.pouch # routine update
herdr plugin action invoke update-major --plugin herdr.pouch # crossing a major
herdr plugin action invoke uninstall --plugin herdr.pouch

herdr-pouch update and herdr-pouch uninstall do the same from a shell. Update advances the checkout and re-links it — Herdr caches the action set at link time, so a release that adds an action answers plugin_action_not_found until it is linked again.

Uninstall keeps your stashed messages. They are your writing, not a cache. --purge deletes them too, --dry-run shows what would go, and --keep-config leaves config.toml alone.

Installs older than 0.3.0 have no update action: cd <checkout> && git pull --ff-only && herdr plugin link "$PWD".

Stash from anywhere — a shell, a script, or one agent preparing work for another:

herdr-pouch add "run the full test suite and report only failures"
herdr-pouch add --pane w1:p3 "now write the changelog entry"
git log -1 --format=%B | herdr-pouch add --agent reviewer

Insert-and-submit ships unbound — every free chord was taken. Bind herdr.pouch.insert-top-submit yourself, or invoke it from the action menu.

Inside the popup:

Clicking a row selects it; clicking it again inserts.

A pouch outlives the pane it was filled for. When that agent is gone the pouch has no destination, so I (or any insert) asks which pane to send to. p, herdr-pouch browse and the Pouch: browse all pouches action are the only way back into an orphan.

1. The pouch is empty — an empty pouch paints nothing, on purpose.
2. A remote client kills all three keys. Herdr applies the foreground client's keybindings to the whole server, and herdr --remote sends a profile that drops every [[keys.command]] entry. Attach with herdr --remote <host> --remote-keybindings server, or use the action menu.
3. herdr plugin action invoke doctor --plugin herdr.pouch, then read herdr plugin log list --plugin herdr.pouch. It says which case you are in.
4. herdr server reload-config after any config edit. Herdr does not hot-reload config.toml.
5. herdr plugin list confirms the plugin is registered at all.

Targets — --here (the calling pane, default) · --pane w1:p3 · --agent <name> (a live agent name, or a saved pouch label). Refs — a 1-based slot number, a message id, or a unique text prefix.

~/.config/herdr/plugins/config/herdr.pouch/config.json. All keys optional.

POUCH_EDITOR, POUCH_CONSUME=1 and POUCH_NO_FOCUS=1 override the file for one run. POUCH_STATE_DIR moves the store.

The count is also a $pouch token for the sidebar:

[ui.sidebar.agents]
rows = [["state_icon", "workspace", "tab", "$pouch"], ["agent"]]

~/.local/state/herdr/plugins/herdr.pouch/ — one JSON file per pouch under pouches/, plus the derived bookkeeping (aliases, pinned strips, tab marks, workspace labels) that sync rebuilds.

A pouch is keyed by (workspace label, cwd, agent), never by pane id: pane ids are not reused, change on move, and are regenerated when the server restarts. So the pouch you filled yesterday is still on the same agent this morning, and renaming a workspace migrates its pouches rather than stranding them. Every write takes a lock and re-reads inside it, so the popup, the strip, the CLI and Herdr's event hooks can never clobber each other.

git clone git@github.com:AltanS/herdr-pouch.git && bun install
herdr plugin link "$PWD" # re-run after ANY manifest change
bun run lint && bun x tsc --noEmit && bun run test

All three gates must pass. bun run test also runs the CLI under both Node and Bun, which is what catches syntax that Node's type-stripping cannot handle. See CLAUDE.md for the versioning rules and the Herdr API traps.

MIT © Altan Sarisin