install · features · keys · keybindings · how it works · configuration
A beads (bd) task board for herdr. Your bd issues as a List, a Table, or a Kanban, docked as a narrow sidebar beside your agents or floating as a full-screen popup. One small Rust/ratatui binary: keyboard-first, mouse-optional, and transparent so your terminal shows through.
bd is where the work lives; herdr-beads is the window onto it. Cards are bd issues, columns are bd statuses, moving a card runs bd update --status, and creating one runs bd create. The board never invents its own store.
- Three views, one keystroke apart (
KorTab), switched in process (instant, no respawn, no lost state):- List: grouped by status, collapsible, one bead per line, with an inline detail pane.
- Table: flat, aligned columns, the only re-sortable view (
ocycles status, priority, changed). - Kanban: one column per status.
vthen arrows retag a card across columns.
- Two surfaces from the same binary, each a single toggle key:
- Docked sidebar: pinned to the left of the tab, narrowed to a sidebar column.
- Floating popup: a wide, full board over your layout.
- Real edits, straight to
bd: claim, close (with a required reason), set priority, add a note (bd note) or a comment (bd comment), and a full create form. - Rich create form (
a): Type, Priority, Title, Description, Assignee, Parent epic, Labels, and a start-in-backlog toggle. Every fieldbd createsupports. - Types at a glance: each row carries a type tag (epic, bug
B, featureF, choreC, spikeS, storyY, decisionD, task), colored so epics stand out. - Detail everywhere (
dorEnter): description, dependencies, notes, and counts, enriched bybd show. It renders below the list in a narrow sidebar, beside it when wide, or as a modal. - Repo-scoped automatically: the board reads the
bddatabase of the herdr window's project.gflips to--globalif you run a shared-server bd database. - Transparent: no solid background. Your terminal theme, image, or blur shows through. Selection and the active tab keep an accent for legibility.
- Mouse-optional: click the view tabs, click a card or row, scroll. Everything also has a key.
Mouse works everywhere; every action also has a key.
| Key | Action |
|---|---|
K, Tab |
cycle view (List, Table, Kanban) |
j k up/down |
move selection |
h l left/right |
kanban: change column. list: collapse or expand a group |
1..9 |
jump to the Nth status group |
[ ] |
jump to the previous or next status group |
Enter |
open the detail modal |
d |
toggle the detail pane (side when wide, below when narrow) |
v |
move mode, then arrows retag the card's status |
c |
claim (sets in_progress and assigns you) |
x |
close (prompts for a reason) |
p |
set priority (0 to 4) |
n |
add a note (bd note) |
m |
add a comment (bd comment) |
a |
open the new-bead form |
o |
table: cycle sort (status, priority, changed) |
/ |
filter. Esc clears it |
g |
scope: repo or global |
C |
show or hide closed |
r |
refresh from bd |
? |
key help overlay |
q |
quit. Esc only backs out a layer, it never quits |
Create form (a): Tab and arrows-up/down move between fields, arrows-left/right cycle Type, Priority, and Parent epic, Space toggles start-deferred, Enter creates, Esc cancels.
Requires herdr 0.7.0 or newer (0.7.5+ is recommended so the plugin loads in every session automatically), a Rust toolchain (the plugin builds from source on install), and bd (beads) on your PATH.
herdr plugin install miiraheart/herdr-beadsPlugins load at server start, so after installing, restart your herdr server (a herdr server live-handoff, then reattach) to activate it. On 0.7.5+ it is then available in every session.
Developing locally? Clone and link it instead:
git clone https://github.com/miiraheart/herdr-beads
cd herdr-beads
herdr plugin link .Bind the two surfaces in ~/.config/herdr/config.toml (the herdr prefix is ctrl+b):
[[keys.command]]
key = "prefix+shift+b" # toggle the docked beads sidebar
type = "plugin_action"
command = "herdr-beads.open-dock"
[[keys.command]]
key = "prefix+shift+k" # toggle the floating beads board
type = "plugin_action"
command = "herdr-beads.open-board"Both keys toggle: press to open, press again to close. The floating popup is session-modal, so while it is focused it grabs all keys. Dismiss it with q or Esc; the toggle key closes it from any other pane.
The plugin also exposes its actions in herdr's command palette: Beads: toggle dock, Beads: open floating board, and Beads: redeploy panes (closes every beads pane so they respawn on a fresh build).
- bd bridge. Every read (
bd list,bd ready,bd show) and write (bd update --status,--claim,bd close -r,bd priority,bd note,bd comment,bd create) is a subprocess call built as an argv vector, never a shell string, so titles, notes, and reasons cannot be shell-injected. Writes are local; syncing (bd dolt push) stays your deliberate step. - Repo resolution. herdr runs the pane in the plugin's directory, so the binary asks herdr (
HERDR_WORKSPACE_IDplusherdr pane list) for the focused pane's working directory and runsbdthere. The board scopes to the project the window is on, with no configuration. - Columns are statuses. The board's groups and columns are
bd's statuses (open,in_progress,blocked,deferred,closed,pinned,hooked, plus any custom ones). Closed is hidden until you pressC. - In-process views. List, Table, and Kanban are three renderers over one selection, kept by bead id, so the selection survives view switches and reloads.
| Board | bd |
|---|---|
| Column or group | issue status |
| Card | a bd issue (bd list, bd ready) |
| Move a card | bd update <id> --status <s> |
| Claim, close, priority | bd update --claim, bd close -r, bd priority |
| Note, comment | bd note, bd comment |
| New bead (epic parent, labels, and more) | bd create -t ... -p ... --parent ... -l ... |
- Keybindings live in
~/.config/herdr/config.toml(see above). - Scope:
gtoggles between the window's repo.beadsandbd --global. Global requires a bd shared-server database (BEADS_DOLT_SHARED_SERVER=1); without one the board says so and stays on repo scope. - Theme: a fixed Catppuccin-Macchiato accent palette on a transparent background, so it blends with any terminal theme.
The board's TUI needs a real terminal, but the bd bridge is fully testable headless:
cargo test # parser unit tests
cd /path/to/a/repo/with/beads
/path/to/herdr-beads/target/release/herdr-beads --selftest # repo scope
/path/to/herdr-beads/target/release/herdr-beads --selftest --global # global scope--selftest prints the grouped board as plain text, the same data the TUI renders.
herdr plugin uninstall herdr-beadsMIT.