herdr-file-viewer

Browse your repo without leaving your terminal session: a git-aware, read-only file viewer that lives in a herdr pane. A keyboard-driven TUI with a directory tree on the left and, on the right, exactly the view each file deserves: a diff if it changed, rendered markdown if it's markdown, syntax-highlighted code otherwise. Git status is woven right into the tree. It opens beside whatever you're doing and never touches your files.

A fork of smarzban/herdr-file-viewer, tracking upstream and adding four things — three that make the mouse behave the way a desktop file list does, and one that puts a shell where you are looking:

Full detail in keys and usage; everything else in this README is upstream's. No prebuilt binaries are published for this fork, so installing it builds from source (Rust 1.96+):

herdr plugin install ryletko/herdr-file-viewer

The CI badge above tracks upstream's pipeline, not this fork's.

The right view per file, here a markdown file rendered (headings, inline code, tables) in your terminal's theme:

…and running full-screen, the same tree + content, filling the terminal:

• The right view, automatically. Stop cat-ing files and squinting at raw diffs. A changed file shows its diff; a README renders; code is highlighted: no mode-switching, no commands.
• Git at a glance. M/A/D/? markers (colored, with the glyph as a non-color cue), a changed-files-only filter, and a baseline you can flip between your branch's merge-base and HEAD — all in the tree, not a separate mode.
• It sits beside your work. Opens in a herdr split (or its own tab) with one keypress, and toggles away just as fast. Great next to an agent, a build, or an editor.
• Safe on anything. Read-only by construction and hardened to open untrusted repos (an agent's worktree, a fresh clone) without running repo-controlled code or letting hostile file content drive your terminal. See SECURITY.md.
• Keyboard-first, mouse-optional, and it never reinvents rendering: it delegates to glow / delta / bat and degrades gracefully when they're absent.

A taste of what the keys do — the full key & mouse reference has them all, and the usage guide walks through each feature:

# 1. Install the plugin (downloads a prebuilt binary for released versions; otherwise builds from source):
herdr plugin install smarzban/herdr-file-viewer

# 2. (recommended) install the renderers, so markdown / diffs / code are styled, not plain text:
brew install glow git-delta bat     # macOS, or use your package manager
#   Linux / cross-platform: run scripts/install-renderers.sh from the plugin dir (`herdr plugin list`)

Then bind a key in your herdr config (~/.config/herdr/config.toml) so one press summons it:

[[keys.command]]
key = "prefix+f"
type = "plugin_action"
command = "herdr-file-viewer.open-file-viewer"
description = "open file viewer in split"

[[keys.command]]
key = "prefix+shift+f"
type = "plugin_action"
command = "herdr-file-viewer.open-file-viewer-tab"
description = "open file viewer in tab"

Run herdr server reload-config, then press your key. That's the whole setup: the split-pane viewer and its open actions ship inside the plugin and register automatically on install, so you only add the keybinding.

Deeper detail lives in the docs: install & updating, summoning the viewer (split vs. tab, the launcher, --remote), external renderers, and the keys reference.

An optional, read-only TOML config file lets you override the editor, the renderer/opener commands, a couple of startup toggles, the tree layout, and the keybindings. A fully-commented config.example.toml ships in the plugin folder; copy it as config.toml into the directory herdr plugin config-dir herdr-file-viewer prints, then uncomment what you want.

The full reference — file location, precedence, every key, and [keys] remapping — is in docs/configuration.md. See your effective settings any time in the ? help overlay's Settings section.

Native Windows is supported as a preview (install works the same way; the open actions use -windows action ids and herdr's preview channel). WSL works today with zero extra setup. See docs/windows.md.

Full docs live in docs/:

• Install & updating — prebuilt vs. source, pinning a version, local-dev linking, and remote notices.
• Summoning the viewer — the open actions, the idempotent launcher, split vs. tab, and the --remote caveat.
• Usage guide — a feature-by-feature tour of the whole viewer.
• Keys & mouse — the complete key table, mouse gestures, and editor hand-off.
• Configuration — the full config.toml reference and [keys] remapping.
• External renderers — the optional glow / delta / bat integrations and the plain-text fallback.
• Windows (preview) — native-Windows specifics and WSL.
• Architecture — one in-process TUI owning both columns, the component map, and the load-bearing decisions.
• Security — the threat model for opening untrusted content, and how to report a vulnerability.

Bug reports and feature requests are very welcome — please open an issue. To build, test, and send a change, see CONTRIBUTING.md.

MIT © Saeed Marzban