Skip to content

About

MRU switching across recent workspaces, tabs, panes, and agents — like JetBrains's recent file — plus fuzzy search over any pane's content, fully keyboard-driven.

Resources

Stars

0 stars

Watchers

0 watching

Forks

 
 

Repository files navigation

Herdr Recent Navigator

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.

Screenshot

Herdr 0.7.4+ Linux and macOS Release CI MIT License

Demo

demo

cmd

cmd

Features

  • 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.focused events to build MRU history
  • 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%

Install

Warning: Requires Herdr ≥ 0.7.4. Check with herdr -V.
To upgrade Herdr, see herdr.dev/docs/install/#update.

Choose one of the following:

A. Quick install (curl | bash)

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 | bash

Recommendation: Use this method — no Rust toolchain required.

B. Install via Herdr plugin manager

herdr plugin install beyondlex/herdr-recent-navigator

Herdr clones the repo, builds from source, and registers the plugin automatically.

C. Build from source (manual)

git clone https://github.com/beyondlex/herdr-recent-navigator
cd herdr-recent-navigator
cargo build --release
herdr plugin link "$PWD"

Upgrade

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"

Bind a shortcut

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-config

Press the shortcut to open the navigator popup.

Quick-focus: jump to previous tab/pane/agent without opening the UI

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.

Configuration

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-navigator

Create 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

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.

Keybindings

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"]

Key syntax

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.

Default bindings

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

Input modes

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.

Tab order and visibility

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 all only
  • others is accepted as a legacy alias for all

Usage

Type-to-search (default keybindings)

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

Vim-style (movement bound to a printable key)

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.

Category tabs

  • 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

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.

License

MIT

About

MRU switching across recent workspaces, tabs, panes, and agents — like JetBrains's recent file — plus fuzzy search over any pane's content, fully keyboard-driven.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages