LazyHerdr

A local Herdr session manager with a mouse-capable terminal UI built on OpenTUI. It polls Herdr's CLI JSON APIs and presents sessions, workspaces, tabs, and panes so you can inspect and steer active work without leaving the terminal.

Requirements

• Bun
• Herdr CLI available as herdr or via HERDR_BIN
• Terminal UI with mouse support

Run

Install the published CLI globally:

npm install -g lazyherdr
lazyherdr

Or run it from a local checkout:

bun install
bun run start

The app polls the selected session's herdr api snapshot every second and keeps the last successful snapshot when the server becomes unavailable.

What it manages

• Named Herdr sessions from herdr session list --json
• Workspaces and tabs in the selected session
• Panes and detected agents in the selected tab
• Recent pane output from the selected pane
• Focus actions for workspaces, tabs, and agents
• Local dark/light UI theme, persisted in ~/.config/lazyherdr/config.json

Controls

• Click a session, workspace, tab, or pane to select it.
• Use the mouse wheel over Details / Output to scroll pane output.
• Click footer actions to focus, switch session, toggle theme, refresh, show help, or quit.
• Keyboard: j/k or arrows move, h/l or arrows switch panels, z zooms/restores output, / searches output, n/N moves between matches, F follows/pauses live output, g/G jumps to the top/bottom, [ / ] switch sessions, c copies a direct locator command, t toggles theme, Enter focuses, r refreshes, ? toggles help, and q quits.
• Search is Grep-style: submit a query with /, then use R for regex, C for case-sensitive matching, V to invert the match, and X to show only matched lines. + / - grows or shrinks the filtered context radius; every matched line is highlighted while n/N keeps the active match emphasized and in view. Invalid regular expressions are reported inline instead of breaking output rendering.
• In Details / Output (or output zoom), press i to enter terminal input mode for the selected pane. Typed characters, Enter, Escape, arrows, Backspace, Tab, Ctrl/Alt chords, and pasted text are forwarded to that Herdr pane. Press Ctrl-] to return to LazyHerdr controls; Ctrl-C is forwarded to the target pane so it can interrupt the running process there.
• Drag across selectable output text, then press y or Ctrl-C to copy that selection to the macOS clipboard. Ctrl-C only quits when there is no text selection and terminal input mode is not active.
• Press e while Details / Output is active to export the current pane's plain-text output to the system temp directory under lazyherdr/. The exact generated .txt path is shown in the footer.
• Press c on a selected session, workspace, tab, agent, or pane to copy its executable locator command to the macOS clipboard. Stopped sessions use herdr --session <name> so Herdr can start or attach the named session. Ordinary panes use pane get because Herdr has no direct pane-focus-by-ID command.

Set HERDR_BIN to override the Herdr executable path. Set LAZYHERDR_CONFIG_PATH to override the theme config path.

Product boundary

LazyHerdr stays a management client, not a second terminal multiplexer. It reads Herdr's public CLI JSON output, targets named sessions with herdr --session <name> ..., and does not parse terminal UI screens or read Herdr internal persistence files. Terminal input mode forwards ordered key batches through Herdr's public pane send-keys API; LazyHerdr does not take ownership of the target PTY.

License

MIT