Features • Install • Keys • Configuration • Troubleshooting • Development • License
A sidebar for Herdr that shows which agent is working, which one waits on you, and which finished while you were away. It only watches and paints: it never starts, prompts or stops an agent.
This repository, killallgit/herdr-scope, is a fork of kriuchkov/herdr-scope by Nikita Kriuchkov. His original Herdr Scope implementation is the foundation for this fork's development. The original MIT copyright and license remain in LICENSE; additional attributions are in THIRD_PARTY_NOTICES.md.
- State at a glance: a spinner while an agent works, a red
?when it asks, a green✓held until you look, and idle rows that fade with age. - Grouped by project: worktrees and nested folders hang under their repository, and the busiest group comes first.
- Vendor marks: 27 agents, each with its own mark and colour, from the icon font or plain Unicode.
- Jump:
prefix+ugoes to the next agent waiting on you. - Fold and filter: fold a folder to one line, or show only the workspace you are in.
- Tab bar:
?1 ✓2before the path, and a waiting tab's name ends with its mark. - Settings popup: every option is validated and applied without a restart.
- Light: one Go binary and one daemon per session. Nothing goes over the network.
| State | Row |
|---|---|
| working | braille spinner, title in the vendor's colour |
| waiting on you | red, the ? pulses |
| done | green ✓, until you focus the pane |
| idle | fresh → plain → stale; a stale row dims |
herdr plugin install killallgit/herdr-scope --ref releaseThe release branch carries prebuilt binaries for macOS (amd64/arm64) and Linux (amd64) once
published for this fork. Without --ref, Herdr builds from source using the Go version declared in go.mod. Without Go, it downloads the release binary and checks its checksum. Setup
adds Scope's blocks to Herdr's config.toml between HERDR-SCOPE markers and installs the
icon font for your user. It requires Herdr 0.9+ (protocol 22).
Important
If the sidebar has not changed, start the daemon:
herdr plugin action invoke killallgit.herdr-scope.state-start.
Never run herdr server stop to restart anything: it ends every pane.
To update, restart the daemon after updating the plugin. To uninstall, run these in order;
your config.toml comes back byte for byte:
herdr plugin update killallgit.herdr-scope # update
herdr plugin action invoke killallgit.herdr-scope.state-start
herdr plugin action invoke killallgit.herdr-scope.unconfigure # uninstall
herdr plugin action invoke killallgit.herdr-scope.uninstall-font
herdr plugin uninstall killallgit.herdr-scopeScope binds no keys itself. bin/herdr-scope configure --keys prints the snippet for
config.toml, one [[keys.command]] per row:
| Key | Action | Does |
|---|---|---|
prefix+u |
jump |
the next agent waiting on you: questions first, then unseen results |
prefix+a |
view-flip |
order: active ↔ recent |
prefix+f |
view-here |
only this workspace ↔ all |
prefix+m |
fold |
fold ↔ unfold this folder; agents waiting on you, or alone in it, stay visible |
prefix+, |
settings |
the settings popup |
[[keys.command]]
key = "prefix+u"
type = "plugin_action"
command = "killallgit.herdr-scope.jump"This fork uses plugin ID killallgit.herdr-scope, with separate configuration and
state directories from upstream installations. Existing settings and key bindings
are not migrated automatically. Before switching, unconfigure and uninstall the
upstream plugin using its own instructions; keep a backup of your settings.
prefix+, opens the popup: ↑↓ select, ←→ change, s save. A save is validated and
applied at once. The most used options:
| Option | Default | Values |
|---|---|---|
layout |
classic |
classic (§ · ✓ title) or compact (§ ✓ title, denser) |
order |
active |
active by activity, recent, here (this workspace), off (Herdr's) |
variant |
auto |
font icons, text (plain Unicode), none; auto picks what the terminal can draw |
show_age |
waiting |
? 4m, ✓ 12m on rows waiting on you; all or off |
done_hold |
until_seen |
keep the ✓ until you look, or for a duration ("30s") |
mark_tabs |
true |
end a waiting tab's name with ? or ✓ |
nest_folders |
true |
hang a workspace opened inside another one's folder under it |
Every option and the file format are covered in docs/configuration.md.
bin/herdr-scope doctor # binary, protocol, socket, config, font, sidebar
bin/herdr-scope status # daemon, connection, agents, last frame- Boxes instead of logos. Ghostty and kitty draw the icons once the font is installed.
iTerm2, Terminal.app and Windows Terminal need them in their own font:
herdr-scope font patch <font>.ttf, then pick the… Herdrcopy in the profile (dist/JetBrainsMonoHerdr-Regular.ttfis a ready-made one). Or setvariant = "text". - Rows unreadable on a light terminal. Scope colours its rows for Herdr's theme, not for the
desktop. Set a light theme:
[theme] name = "catppuccin-latte". - A block was skipped. Your
config.tomlalready declares[theme.custom]or[ui.sidebar.*], and TOML allows a table only once. Merge them by hand.
The daemon logs to scope.log in the plugin's state directory. The log holds ids and
statuses, never prompts or titles. Like any Herdr plugin, Scope runs as you, unsandboxed.
make build # bin/herdr-scope; the next state-start restarts the daemon on it
make check # pinned formatting, modules, workflows, lint, security and race/coverage gates
make race # offline unit, architecture, contract and golden tests
make lint # pinned golangci-lint for the host platform
make golden # rewrite tests/golden after an intended change to the lookFrom a checkout: make build && herdr plugin link . (plugin link runs no build step).
Architecture, Herdr protocol notes,
design decisions, CI and test tooling.
docs/demo/record.sh re-records the GIF.
Run a non-publishing release rehearsal on the branch to run the full CI suite and package all three platform binaries:
gh workflow run release.yml --ref <branch>Manual runs upload the release artifacts but skip publishing. To publish after
merging, keep herdr-plugin.toml and internal/bootstrap/version.go at the same
new version, then push its vX.Y.Z tag. The release workflow publishes the
archives, checksums, vX.Y.Z-bin tag, and (for stable versions) release branch.
MIT, see LICENSE. The icon font is forked from qintmb/herdr-icon-agent-ui (MIT), and vendor marks belong to their owners. Details are in THIRD_PARTY_NOTICES.md.
