herdr-plugins

a vs code-style sidebar, live preview, and git for herdr

herdr · GitHub

git clone https://github.com/stevederico/herdr-plugins.git
cd herdr-plugins
(cd sidebar && cargo build --release)
herdr plugin link ./sidebar
herdr plugin link ./git-badge
herdr plugin link ./space-title
herdr plugin link ./space-status
herdr plugin link ./agent-picker

Focus a tab. The sidebar docks to the right of the agent. Click a file: the preview opens on the far right.

Recommended herdr chord (plugins cannot ship keybinds — paste into ~/.config/herdr/config.toml, then herdr server reload-config):

[[keys.command]]
key = "prefix+f"
type = "plugin_action"
command = "herdr-sidebar.open-sidebar"
description = "toggle file tree"

Same snippet: sidebar/keys.example.toml.

Rebuild later:

(cd sidebar && cargo build --release)
herdr plugin action invoke herdr-sidebar.redeploy

Then click the file again so the preview process picks up the new binary.

Steve's local herdr plugins in one repo. herdr-sidebar is the product. The others are small workspace helpers.

• VS Code-style tree in one dockable pane: single-click folders, Material or emoji icons
• Filter as you type (/ or click the box at the bottom) hides non-matching files
• Follows the agent cwd so the tree tracks the Grok pane you are in
• Re-root on double-click; parent up-arrow when macOS hides the listing
• Context menus (right-click): new file, new folder, rename, delete, copy path, Open in Finder (macOS)
• Gear in the header (s) for icons, hidden files, preview, folder

• Opens beside the agent (agent | preview | explorer) so the tree keeps ~32 columns. One viewer per tab; clicks reuse it
• Live-reloads from disk when an agent (or anything else) writes the open file. Markdown included. ~80ms
• Markdown opens Rendered. Lines wrap to the pane. Click the chip for Raw. Type in Rendered to drop back into Raw. Click a box to toggle tasks
• Edit: type, Ctrl+S to save, Ctrl+A / Ctrl+C to copy
• Images and video rasterize in the pane. o opens the real file at full resolution
• Full-size preview (default on): other panes park while you read; Esc restores them

• Stage, unstage, commit, sync with a VS Code-shaped diff (dual gutters, tinted rows)
• ✧ suggest writes a commit subject from the pending diff (claude CLI, filename fallback)
• Graph, commits, file history, branches, worktrees, remotes, stashes, tags
• Diffs in the built-in renderer

• git-badge puts * next to the folder name when the worktree is dirty or unpushed
• space-status clears leftover status emoji tokens on spaces (Agents sidebar stays plain)
• space-title names spaces from the project folder (stops once you rename) and puts the Grok/agent session title on the subtitle. If the pane still sits in ~/Projects (or ~), it infers the git repo from this session's tool paths and memory topics, then chat mentions. Pins the Grok session UUID (grok-resume resumes it after a pane reset)
• agent-picker popup walks agents like workspace navigate (highlight → Enter). Bind prefix+up / prefix+down to herdr-agent-picker.open-up / open-down
• explorer is a thin leftover file tree. Keep it disabled if you run the sidebar

herdr-sidebar needs herdr 0.7.0+. Linux, macOS, Windows.

Hotkey chips live in Settings. Footer chips are off by default.

Disk wins: if the file changes on disk, the pane reloads even while you watch an agent write it.

Gear in the sidebar header, or s.

This repo lives at ~/Projects/herdr-plugins on the author machine. Plugin links store absolute paths. Move the repo, then unlink and relink or every plugin shows manifest unavailable.

herdr plugin uninstall herdr-sidebar   # if still GitHub-managed
herdr plugin link ~/Projects/herdr-plugins/sidebar
herdr plugin link ~/Projects/herdr-plugins/git-badge
herdr plugin link ~/Projects/herdr-plugins/space-title
herdr plugin link ~/Projects/herdr-plugins/space-status
herdr plugin link ~/Projects/herdr-plugins/explorer   # optional
herdr plugin disable herdr-explorer                   # if you only want sidebar

Verify: herdr plugin list with no warning: lines.

Actions worth knowing:

herdr plugin action invoke herdr-sidebar.open-sidebar    # linux / macos toggle
herdr plugin action invoke herdr-sidebar.open-git        # separate SCM pane
herdr plugin action invoke herdr-sidebar.new-agent       # new workspace + Grok
herdr plugin action invoke herdr-sidebar.redeploy        # respawn every sidebar pane
sidebar/target/release/herdr-sidebar --open-file todos.md  # agent: this tab's preview

Windows uses the -windows action ids (open-sidebar-windows, and so on).

Markdown preview is hand-rolled (sidebar/src/md.rs): no markdown crate. File follow hashes bytes on a short tick; it does not wait on event::poll timeouts.

One herdr-sidebar binary, three roles:

1. Explorer TUI to the right of the agent (--view git still opens source control)
2. --preview <ctl> on the far right: file contents, markdown, media, git diffs
3. herdr-sidebar-ensure windowless sidecar for Windows hooks (no console flash)

The sidebar writes a control file per tab (herdr-sidebar-preview-<pane>.ctl). The viewer polls it and reloads in place, so clicks never churn panes. For an open file it also re-reads the path when the bytes change, so an agent write shows up without another click.

Pane identity is a heartbeat token on pane.report_metadata. Launchers treat a stale stamp as a dead pane and replace it. Focus/create hooks dock a sidebar to the right of the agent per tab and heal corpses after a herdr restart.

git clone https://github.com/stevederico/herdr-plugins.git
cd herdr-plugins/sidebar
cargo test --offline
cargo build --release

git-badge and space-title are scripts. No extra toolchain.

• X: @stevederico
• Issues: GitHub Issues

• herdr - terminal workspace this docks into
• ratatui - TUI toolkit
• syntect / two-face - syntax dumps
• VS Code - explorer + SCM shape

• herdr - terminal multiplexer these plugins run in

(cd sidebar && cargo build --release)
herdr plugin link ./sidebar

MIT License.