A recent workspaces/tabs/panes switcher for Herdr. Opens an popup listing recently focused workspaces, tabs, panes, and AI agents — fuzzy-searchable and navigable by keyboard.
- Four category tabs: Workspaces, Tabs, Agents, Panes — switch with
Tab - MRU ordering: most recently focused items float to the top
- Fuzzy search: type to filter any category
- Customizable quick-jump shortcuts: Bind separate keys to open each tab
directly — e.g.
prefix+u→ Workspaces,cmd+i→ Tabs,cmd+e→ Agents,cmd+shift+n→ Panes - Cross-category filtering: Open the Agents tab and fuzzy-filter by workspace name to find all agents under a specific workspace; similarly filter Panes by tab name, or Tabs by workspace — no need to navigate through the tree
- Live agent status: Working agents show a braille spinner; status updates in real time without reopening
- Follows your Herdr theme: dark (TokyoNight) or light (One Light) palettes, or the host terminal palette when Herdr is set to
terminal, with your[theme.custom]colour overrides applied on top - Automatic tracking: hooks into
workspace.focused,pane.focused,tab.focusedevents to buildMRUhistory - Phone-friendly popup: on a narrow client (under 80 columns, such as Herdr on a phone) the popup opens full width instead of the manifest's 60%
Warning: Requires Herdr ≥ 0.7.4. Check with
herdr -V.
To upgrade Herdr, see herdr.dev/docs/install/#update.
Choose one of the following:
Downloads a prebuilt binary to ~/.local/bin/ and links it into Herdr:
curl -fsSL https://raw.githubusercontent.com/beyondlex/herdr-recent-navigator/main/install.sh | bashRecommendation: Use this method — no Rust toolchain required.
herdr plugin install beyondlex/herdr-recent-navigatorHerdr clones the repo, builds from source, and registers the plugin automatically.
git clone https://github.com/beyondlex/herdr-recent-navigator
cd herdr-recent-navigator
cargo build --release
herdr plugin link "$PWD"| Current install method | Upgrade command |
|---|---|
| curl | bash | Re-run the curl command |
herdr plugin install |
herdr plugin uninstall killallgit.herdr-recent-navigator && herdr plugin install beyondlex/herdr-recent-navigator |
| Build from source | git pull && cargo build --release && herdr plugin unlink killallgit.herdr-recent-navigator && herdr plugin link "$PWD" |
Add to your Herdr config:
[[keys.command]]
key = "cmd+e"
type = "plugin_action"
command = "killallgit.herdr-recent-navigator.focus-workspaces"
description = "Open Navigator: Workspace"
# Optional: Focus Tabs/Panes/Agents when open navigator
[[keys.command]]
key = "cmd+i"
type = "plugin_action"
command = "killallgit.herdr-recent-navigator.focus-tabs"
description = "Open Navigator: Tab"
[[keys.command]]
key = "prefix+u"
type = "plugin_action"
command = "killallgit.herdr-recent-navigator.focus-panes"
description = "Open Navigator: Pane"
[[keys.command]]
key = "prefix+o"
type = "plugin_action"
command = "killallgit.herdr-recent-navigator.focus-agents"
description = "Open Navigator: Agent"focus-agents lists agents most-recently-used first. focus-agents-priority
and focus-agents-grouped order them like Herdr's sidebar in its "priority"
(blocked → done → working → idle, latest status change first) and "grouped"
(workspace → tab → pane) modes.
Reload:
herdr server reload-configPress the shortcut to open the navigator popup.
Three plugin actions focus the most recently focused tab, pane, or agent directly via MRU history, no dialog needed:
[[keys.command]]
key = "prefix+t"
type = "plugin_action"
command = "killallgit.herdr-recent-navigator.focus-previous-tab"
description = "Jump to previous tab"
[[keys.command]]
key = "cmd+y"
type = "plugin_action"
command = "killallgit.herdr-recent-navigator.focus-previous-pane"
description = "Jump to previous pane"
[[keys.command]]
key = "prefix+a"
type = "plugin_action"
command = "killallgit.herdr-recent-navigator.focus-previous-agent"
description = "Jump to previous agent"The tab and pane actions use the second MRU entry, mirroring GNU screen's alt-tab workflow. The agent action skips the currently focused agent; from a non-agent pane it jumps to the most recently focused agent.
User settings live in config.toml inside the plugin's config directory, which
Herdr keeps separate from the plugin files so upgrades never overwrite it:
herdr plugin config-dir killallgit.herdr-recent-navigator
# usually ~/.config/herdr/plugins/config/killallgit.herdr-recent-navigatorCreate config.toml there (the installer seeds a commented template if the
file doesn't exist). theme, [keybindings] and [navigator] all go in this one file:
theme = "terminal"
[keybindings]
move_up = ["Up", "C-k"]
move_down = ["Down", "C-j"]Settings still in herdr-plugin.toml (the old location) are honored as a
fallback, but the installer regenerates that file on every upgrade, so move
anything you've customized into config.toml.
theme = "terminal" # fallback: "terminal" | "dark" | "light"The navigator follows your Herdr theme. The active theme name is resolved from
Herdr's HERDR_PLUGIN_CONTEXT_JSON when available, then from [theme] name in
your Herdr config, then from this setting:
terminal— inherit the terminal's own colours (default foreground/background plus ANSI accents). Use this when Herdr is configured with[theme] name = "terminal".- a light theme name (
*-light,*-latte,*-day,*-dawn,*-lotus) — the built-in One Light palette. - anything else, including an unset theme — the built-in dark (TokyoNight) palette, so the popup matches Herdr's UI rather than the host terminal.
Herdr does not currently expose theme colours to plugins, so a Herdr theme the navigator has no dedicated palette for is approximated by the built-in dark or light palette.
Colour overrides from Herdr's [theme.custom] table are applied on top of the
palette, in the same order Herdr uses (built-in theme, then custom). A custom
accent, panel_bg, surface0, text, selection_bg, and so on are therefore
respected. Values accept hex, rgb(r,g,b), reset aliases (reset, default,
none, transparent) and common named colours. panel_bg maps to the popup
background and to the accent-background text (the active tab and filter chips);
it is the colour Herdr fills the plugin-popup frame with, even though Herdr's
config reference only shows it in examples. selection_bg / active_row_bg map
to the selected row. sidebar_bg is desktop-sidebar-only and has no popup
equivalent, so it is not mapped. Herdr's surface_dim
(separators, scrollbars) and surface1 (dragged rows) are not mapped. The
[theme.custom.light] / [theme.custom.dark] sub-tables are ignored, because a
plugin is never told the current light/dark appearance.
All internal navigation keys are configurable via the [keybindings] section.
Each action accepts a list of key strings (multiple bindings per action).
[keybindings]
next_category = ["Tab"]
previous_category = ["S-Tab"]
move_up = ["Up", "C-p"]
move_down = ["Down", "C-n"]
select = ["Enter"]
dismiss = ["Esc"]
force_quit = ["C-c"]
backspace = ["Backspace"]| Format | Meaning |
|---|---|
Tab, Up, Down, Enter, Esc, Backspace, Space |
Special keys |
S-Tab |
Shift+Tab (same as BackTab) |
a...z, 0...9 |
Literal character |
C-a...C-z |
Ctrl + character |
S-a...S-z |
Shift + character |
M-a...M-z or A-a...A-z |
Alt + character |
C-S-a |
Ctrl + Shift + a |
C-M-a |
Ctrl + Alt + a |
Note: Terminal support for Alt+key combinations is limited. Some
terminals send Esc + key instead of a distinct Alt+key event. Prefer
Ctrl-based combinations when possible.
| Action | Default keys | Description |
|---|---|---|
next_category |
Tab |
Next category tab |
previous_category |
S-Tab |
Previous category tab |
move_up |
Up, C-p |
Move selection up |
move_down |
Down, C-n |
Move selection down |
select |
Enter |
Focus selected item |
dismiss |
Esc |
Step back: leave filter → clear query → close |
force_quit |
C-c |
Close without focusing |
backspace |
Backspace |
Delete last query character |
By default the navigator is modeless: every printable key goes straight into
the query, so typing filters immediately and j, k and / are just text.
Binding a printable key to a navigation action — j/k on movement, or a
letter on next_category — turns on the modal style, because a key cannot both
move the list and be typed:
[keybindings]
move_up = ["k", "Up"]
move_down = ["j", "Down"]In modal use, j/k always move the list, h/l switch category tabs, /
enters filter mode, and printable keys edit the query while filtering (so a query
can still contain j, k, h and l).
Esc steps back one layer at a time: leave the filter, then drop the query, then
close. Nothing else to configure: which style you get follows from which keys you
bound. The mode shows up in the bottom hints and in the prompt colour, never as a
mode label taking a row.
The order of the top-level category tabs — and which tabs appear at all — is
configured with a single array in the plugin's config.toml (see
Configuration): position is display order, and a tab left
out of the list is hidden entirely. Like theme and [keybindings],
herdr-plugin.toml is only read as a fallback when config.toml has no
[navigator] section — the installer regenerates the manifest on upgrade.
[navigator]
tabs = ["workspaces", "tabs", "panes", "agents", "all"]- Valid names:
workspaces,tabs,panes,agents,all - Unknown names are ignored; duplicates collapse to the first occurrence
- At least one tab is always kept — an empty (or all-invalid) list falls back
to
allonly othersis accepted as a legacy alias forall
| Key | Action |
|---|---|
Type text, Backspace |
Filter the list as you type |
↑ / ↓ or Ctrl+P / Ctrl+N |
Navigate the list |
Tab / Shift+Tab |
Cycle category tabs |
Enter |
Focus selected item |
Esc |
Clear the query, then close |
Ctrl+C |
Close without focusing |
| Key | Action |
|---|---|
j / k, ↑ / ↓, Ctrl+N / Ctrl+P |
Navigate the list |
/ |
Enter filter mode, keeping the current query |
Type text, Backspace |
Edit the query while filtering |
Tab / Shift+Tab |
Cycle category tabs in either mode |
h / l |
Previous / next category tab (outside filter mode) |
Enter |
Focus selected item |
Esc |
Leave filter mode keeping the query; again clears the query; again closes |
Ctrl+C |
Close without focusing |
Which table applies is decided by your [keybindings], see
Input modes. Navigation, category, select, dismiss and backspace
bindings are configurable in both styles — see Keybindings.
- Workspaces: MRU workspaces with dot indicators for agent status.
Linked git worktrees show as
<repo> ⎇ <worktree>directly under their main-checkout workspace, and typing the repo name finds them - Tabs: MRU tabs within those workspaces
- Agents: AI agents sorted by last activity
- Panes: Individual terminal panes
- All: find panes by runtime state and buffer content in one list:
- Runtime state — ssh target, foreground command, cwd, listening port, owning pid
- Buffer content — any query also substring-matches pane scrollback and shows a one-line excerpt around each hit
- Filter prefixes narrow the search and show as a badge next to the
input (label + space):
cmd,ssh,cwd,file,term— that source only.— buffer content only (.file= file buffers only)ws/tab/pane— swap to the workspace, tab or pane list, then fuzzy-filter it by name (ws auth= workspaces matching "auth",pane nvim= panes matching "nvim")port/pid— locate a pane by its OS footprint; see Locate a pane by port or pid
In the All tab, port 3000 lists every pane that owns a listening TCP
socket on port 3000 — leave the number off (port ) to list every port a
pane is serving — and pid 12345 lists the pane whose shell started that
process. Selecting a row jumps to the pane.
Attribution walks the process parent chain up to the pane's shell, so
background jobs and dev-server children (e.g. the vite behind npm run dev)
resolve to the pane that launched them. Processes outside every pane —
Docker Desktop's port proxy, system services, servers whose starting shell
has since exited — are shown as dim status rows with the reason in red
(e.g. [::1]:4321 + red (not in any pane), plus the owning command)
rather than dropped; selecting one closes the navigator without focusing
anything. An empty result therefore means the port has no listener at all
(or the pid is gone), and that is stated on a red status row too. The
process/port snapshot refreshes every few seconds while the All tab is
open; a just-started server may take a moment to appear.
MIT



