alexarthurs/herdr-sidebar

Herdr Sidebar

The sidebar your terminal was missing — inspired by VS Code.

A file explorer and a full source-control panel in one dockable herdr pane — activity-bar switching, mouse-driven controls, AI-drafted commit messages, and file previews that open as editor tabs — ephemeral until you double-click to pin one.

If you've ever alt-tabbed out of your terminal just to look at the tree, the diff, or what's staged, this closes that loop.

herdr plugin install alexarthurs/herdr-sidebar/plugins/herdr-sidebar

Tagged releases use SHA-256-verified binaries on supported platforms and fall back to a source build when needed.

The activity bar switches Explorer, Search, and Source Control instantly in one process. Use the mouse or press 1, 2, and 3.

• Navigate a real expandable tree with file icons, hover actions, Git decorations, and m / Ctrl+right-click context menus.
• Click a file to reuse an ephemeral preview tab; double-click to pin it. Preview in the same tab with Preview opens in: pane, or opt into experimental replace mode: working panes move to a temporary tab while you preview; Esc / q brings them back.
• Preview text, Markdown, images, and—when ffmpeg is available—video poster frames. Read-only previews support mouse selection and clipboard copy, including OSC 52 over SSH, and reload on their own when the file changes on disk.
• Find files with Ctrl+P; search project contents with Ctrl+F or Ctrl+Shift+F. Search supports case, whole-word, regex, and include/exclude filters.
• Stage files or folders from the tree without crossing nested-repository boundaries.
• Opt into a terminal editor for mouse clicks, while Enter keeps the built-in preview.
• Press e in a text preview for the experimental editor with selection, find, clipboard actions, explicit save, and external-change protection.

Takeover caveat: after a herdr restart or an incomplete restore, move any remaining working panes back manually. Third-party TUIs are not yet verified with takeover; tab remains the default.

• Stage, unstage, discard, commit, inspect diffs, and sync with the upstream.
• Click the branch name—in the panel header, a repository row, or the Git footer—to switch branches, create one with New branch…, or track a remote branch. Deleting an unmerged branch requires a separate force-delete confirmation.
• Toggle changed files between list and folder tree with t, the view button, or Settings. In tree view, use ←→ to fold folders and m to stage or unstage a folder.
• Use one commit box per repository in multi-repo folders.
• Draft a commit message with the ✧ button through the local claude CLI, with a filename-based fallback when Claude is unavailable.
• Browse commits, file history, branches, worktrees, remotes, stashes, and tags.
• Keep branch and sync controls visible in every sidebar view with the compact Git footer; hide it from Settings if you prefer the extra row.
• Status refreshes while the pane is focused. To keep a Source Control pane updating as a passive monitor (for example beside an agent), launch it with HERDR_SIDEBAR_BACKGROUND_REFRESH=1 in its environment.

The current version appears at the top. Official GitHub installations offer Update & refresh when a newer stable release is available; linked development checkouts stay untouched.

Settings persist across tabs and restarts. Configure:

• Unified or separate Explorer and Source Control panes
• Left/right docking and preferred width
• Material/emoji icons and VS Code/light/terminal colors
• Tab (default), split-pane, or temporary takeover previews and optional custom editor
• Source Control list/tree view (shared across sidebars)
• Hidden files, Git decorations, Git footer, and footer hotkeys
• Auto-open, strict open/close toggle, focus-on-open, and live folder following

The sidebar follows a neighbouring pane's working directory by default. A manually chosen folder stays put until that pane changes directory again.

Preview: drag to select (releasing copies, following herdr's copy_on_select), Ctrl/Cmd+C to copy, arrows/PageUp/PageDown or Space/b to scroll, w to toggle wrapping, and q or Esc to close.

Host keybindings can invoke the direct show-explorer, show-search, show-git, and quick-open actions. For example, bind cmd+p to:

[[keys.command]]
key = "cmd+p"
type = "shell"
command = "herdr plugin action invoke quick-open --plugin herdr-sidebar"

Requirements: herdr 0.8+. Source builds require Rust 1.89+. A Nerd Font is recommended for material icons; the emoji theme works everywhere.

herdr plugin install alexarthurs/herdr-sidebar/plugins/herdr-sidebar

Local checkout:

cd plugins/herdr-sidebar
cargo build --release
herdr plugin link .

Open or toggle it:

herdr plugin action invoke herdr-sidebar.open-sidebar-windows   # Windows
herdr plugin action invoke herdr-sidebar.open-sidebar           # Linux / macOS

Useful development actions:

Use the -windows suffix for each direct action on Windows.

All docking, metadata, pane creation, and preview control use herdr's socket API directly. The plugin is one Rust crate; optional external tools only enhance Markdown (glow), video posters (ffmpeg), and AI commit drafts (claude).