herdr-sidebar puts a file explorer and a git panel in one dockable terminal pane

One dockable pane holds the explorer, the search and the source control

herdr-sidebar is a single Rust plugin that gives the herdr terminal a dockable pane, and that pane switches between three views without leaving the process. An activity bar picks between Explorer, Search and Source Control, and the number keys `1`, `2` and `3` do the same thing for people who never touch the mouse.

Staging and diffs therefore happen in the same pane as file navigation, which is the whole point of the project. Most of the rest follows from that decision: the commit box lives in the source control view, the file picker arrives as a preview tab inside the explorer, and the compact Git footer can stay visible in every view so the branch name and the sync control never scroll out of reach. A setting decides whether Explorer and Source Control share one pane or take two.

Those choices persist across tabs and restarts. Docking side, preferred width, material or emoji icons, VS Code, light or terminal colour schemes, hidden files, Git decorations and footer hotkeys are all configurable, along with auto-open, focus-on-open, and a strict open and close toggle for people who want the pane to behave like a fixed panel rather than a transient one.

Install pulls a checksummed binary and only compiles when no build matches

One command registers the plugin with herdr:

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

Tagged releases ship SHA-256-verified binaries on supported platforms, and installation falls back to a source build when there is no binary for the machine. That fallback is why the requirements section names a toolchain: herdr 0.8 or newer, and Rust 1.89 or newer for the source path. Fonts are a preference rather than a dependency, since a Nerd Font is recommended for the material icon theme while the emoji theme works anywhere.

Working on the plugin itself means building the crate and linking it into the running herdr:

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

Once linked, the pane is opened by action name, and every direct action carries a Windows suffix:

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

Previews open as throwaway tabs until a double-click pins them

Clicking a file in the tree opens an ephemeral preview tab, and a double-click pins it. The default is `Preview opens in: pane`, which reuses the current tab. An experimental `replace` mode takes a different route: working panes move aside to a temporary tab while you look at the file, and Esc or `q` brings them back.

The README attaches its warning to exactly that mode, and the warning is specific rather than general. After a herdr restart or an incomplete restore, working panes have to be moved back by hand, because third party TUIs are not yet verified with takeover. `tab` stays the default for that reason.

Content handling draws the same line between what is built in and what is borrowed. Text and Markdown render on their own, images render on their own, and video poster frames appear only when `ffmpeg` is on the machine. Read only previews take mouse selection and clipboard copy, and the copy path works over SSH through OSC 52. Pressing `e` inside a text preview opens an experimental editor that adds selection, find, clipboard actions, an explicit save, and protection against the file changing underneath you.

Staging from the tree stops at nested repository boundaries

Git work is where a terminal sidebar usually goes thin, and this one is explicit about one rule: staging from the tree never crosses a nested repository boundary. A folder level action in the parent will not sweep up files that live inside a nested checkout, which is the behaviour that makes bulk staging safe in a monorepo.

The changed file list toggles between a flat list and a folder tree with `t`, the view button, or Settings, and that setting is shared across sidebars. In tree view, `←→` fold and unfold folders and `m` stages or unstages a whole folder. In a directory holding several repositories, each one gets its own commit box rather than a single box guessing which repository you meant.

Branch switching is a click on the branch name wherever it appears: the panel header, a repository row, or the Git footer. The same menu creates a branch or tracks a remote one. Deleting an unmerged branch is separated out behind its own force delete confirmation, so a mistyped delete does not take unmerged work with it. Past staging, the panel browses commits, file history, branches, worktrees, remotes, stashes and tags.

Commit drafts call the local claude CLI, with filenames as the fallback

One button in the commit box drafts the message by shelling out to a local `claude` CLI. When Claude is not installed or not reachable, the plugin falls back to a message assembled from filenames. That fallback is a worse sentence, and it keeps the commit path working on a machine with no model at all.

The same reasoning covers the other external tools. `glow` improves Markdown previews, `ffmpeg` produces video poster frames, and `claude` writes commit messages. None of the three is required, which is visible in the fact that the pane itself needs nothing outside the plugin.

All docking, metadata, pane creation and preview control go through herdr's socket API directly, and the plugin is one Rust crate. That split is the install story in a sentence: the crate is the part you always need, the three commands are the part you can lose. The repository root says the same thing, with `plugins/` holding the plugin, `tools/` holding supporting scripts, and `herdr-layout.yaml` beside them. Releases are tagged from the repository itself, most recently v0.15.0 for temporary previews and richer source control, after v0.14.0 for safer previews and Linux ARM64.

Search, quick open, and host keys that reach straight into the pane

Finding files and finding text are separate actions here. `Ctrl+P` opens the picker, `Ctrl+F` searches inside the current view, and `Ctrl+Shift+F` searches project contents. Content search carries case, whole word, regex and include or exclude filters, which is the argument for doing it inside the sidebar rather than piping to an external grep and losing the tree around the results.

Movement is modal in the usual terminal fashion. `↑↓` or `jk` moves, `←→` or `hl` folds, `Enter` toggles or previews, `.` toggles hidden files, `r` refreshes, `m` opens a context menu, `s` opens settings, and `b` hides the sidebar. Source Control remaps the same keys around staging: `Enter` stages or unstages a file, `a` and `u` stage all or none, `c` opens the commit message box, `A` drafts a message, `S` syncs, and `o` opens a diff. Inside a preview, `w` toggles wrapping and `q` or Esc closes it.

Because the host owns the keymap, four actions are exposed for it to invoke: `show-explorer`, `show-search`, `show-git` and `quick-open`. Binding one looks like this:

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

The sidebar follows a neighbouring pane's working directory

The folder on screen is not fixed. By default the sidebar tracks a neighbouring pane's working directory, so a `cd` in another pane moves the explorer with it. A folder chosen by hand stays where it is until that neighbouring pane changes directory again, and that is the only condition that overrides a manual choice.

The settings list runs longer than that behaviour: pane layout, docking side and width, icon and colour themes, preview mode, an optional custom editor, hidden files, Git decorations, footer visibility and hotkeys, auto-open, the strict open and close toggle, focus on open, and live folder following.

The version number sits at the top of Settings, which is also where updates live. An installation that came from GitHub offers Update & refresh once a newer stable release exists. A linked development checkout is deliberately left untouched, so a rebuild you just made is never replaced by something from the release channel.

What writing your own herdr pane would cost instead

The alternative is writing a pane yourself against the same socket API. herdr exposes docking, metadata, pane creation and preview control, and this plugin talks to all four directly rather than wrapping something higher level, so a hand built pane costs a Rust build plus an understanding of that protocol and gives back only the pieces you implement.

The other route is herdr's own tab switching plus shell tools. That gives up the tree, the diffs and the staged file view, and with them the preview tab lifecycle, the takeover caveat, and the directory following that can move a file explorer out from under a reader mid-task. For someone who needs the tree and the diff in one pane, the plugin supplies that view and accepts that behaviour as the price.

Editorial conclusion

Adopt herdr-sidebar if you already live in herdr and keep alt-tabbing out of it to read a tree or a staged diff, and install it from the tagged command so you get a checksummed binary. Leave it alone if your work sits outside a git repository, since staging and the source control view assume one, or if your panes hold a third party TUI you cannot afford to reopen, because takeover mode is unverified with those. Two things are worth checking before you commit to it: that preview mode is still `tab` rather than the experimental `replace`, and that a linked development checkout is what you want, since Settings offers no Update & refresh for one.

Frequently asked questions

Official sources

1. alexarthurs/herdr-sidebar on GitHub
2. Issues
3. License: MIT
4. README
5. Releases