Herdr Navigator

One fuzzy navigator for every workspace, agent, project, session, remote, directory, and action in Herdr.

Type what you remember. Navigator decides whether to focus, create, attach, hand off, invoke, or run—without making you remember which Herdr surface owns the destination.

prefix+t  →  type  →  Enter

[!IMPORTANT]

Upgrading from v0.3.1 or earlier? Sorry for the one-time breaking rename. Starting with v0.3.2, the plugin ID, binary, config directory, and action prefix are all herdr-navigator. See the migration steps below.

Install

herdr plugin install thanhdat77/herdr-navigator --ref v0.3.3 --yes
herdr plugin action invoke herdr-navigator.open

If the overlay opens, add a shortcut to ~/.config/herdr/config.toml. Invoking open again focuses the existing Navigator in the current workspace instead of opening a duplicate:

[[keys.command]]
key = "prefix+t"
type = "plugin_action"
command = "herdr-navigator.open"
description = "jump to anything"

Upgrade from v0.3.1 or earlier

Sorry for the migration. This completes the rename while the project is still young:

herdr plugin uninstall herdr-picker-plus
herdr plugin install thanhdat77/herdr-navigator --ref v0.3.3 --yes
herdr server reload-config

Replace herdr-picker-plus with herdr-navigator in your Herdr keybindings. Navigator copies your old plugin config and Jump Back state into the new config directory on first run; the old files are left untouched. Local development links should use herdr plugin unlink herdr-picker-plus instead of uninstall.

Reload Herdr, then press prefix+t:

herdr server reload-config

See it in action

Source-aware rows keep live status, tabs, and panes aligned at a glance. Watch the full 17-second demo.

A single result list can move between live Herdr state and things that are not open yet:

• Type a repo name → focus its open workspace, or create one from a project, zoxide, or configured root.
• Type @idle or an agent alias → focus that agent pane.
• Filter remotes → hand off with Herdr's own --remote TARGET --handoff flow.
• Select an external integration → run its configured action.

Why Navigator

| Capability | Why it matters | | --- | --- | | One index across Herdr | Search workspaces, agents, projects, sessions, remotes, directories, Quick Actions, and integrations together. | | Action-aware Enter | Results do not just return paths; they focus, create, attach, hand off, invoke, or run. | | Reuse first | Existing workspaces are focused before new ones are created. Project and directory workspaces sharing a cwd keep separate identities. | | Agents are first-class | Search agent name, status, workspace, cwd, pane/tab/terminal IDs, session ID, and your own aliases. | | Extensible without Rust | Add another tool with a command that returns JSON and a command that opens the selected item. | | No picker dependency | The Rust/ratatui interface runs in a Herdr-managed pane; fzf and tv are not runtime requirements. |

Herdr's built-in navigation remains the simpler choice for a single entity type. Navigator is for the moment when “where next?” could mean a workspace, agent, path, session, remote, project, or action.

Standout features

| Feature | What it does | | --- | --- | | Last Workspace | herdr-navigator.jump-back toggles between the current and previously visited local workspace. | | Pin | Ctrl-B marks important entries and keeps them ahead of the normal source order. | | Open with Template | Alt-Enter by default applies one reusable Herdr Plus tabs/panes template to any zoxide/root directory, creating its workspace or appending fresh template tabs when already open. |

What it can open

| Source | Data | Enter does | | --- | --- | --- | | workspace | herdr workspace list + pane cwd | Focus the exact workspace | | agent | herdr agent list | Focus the agent pane | | project | Herdr Plus project TOML | Reuse or create a project workspace and apply tabs and split panes | | session | Herdr sessions + configured local entries | Attach the local session | | server | Configured remote targets | Hand off to the remote Herdr server | | zoxide | zoxide query -l | Enter opens normally; Alt-Enter applies the shared template | | root | Configured filesystem roots | Enter opens normally; Alt-Enter applies the shared template | | quick | Herdr Plus Quick Actions | Open the Quick Actions picker | | plugin | Command/JSON integrations | Run the configured open command |

Every source can be disabled. Missing optional tools degrade quietly.

Keyboard workflow

| Key | Action | | --- | --- | | type | Fuzzy search | | Enter | Open selected item normally | | Alt-Enter | Apply picker.directory_template to the selected zoxide/root directory | | Up / Down | Move selection | | Tab | Cycle source filters | | Ctrl-W | Workspaces | | Ctrl-A / @ | Agents, using configured status order | | Ctrl-P | Herdr Plus projects | | Ctrl-Q | Herdr Plus Quick Actions | | Ctrl-S | Remotes | | Ctrl-L | Sessions | | Ctrl-Z | Zoxide | | Ctrl-R | Roots | | Ctrl-X | Close the open workspace matching the selected item | | Ctrl-B | Mark or unmark the selected item | | Ctrl-O | Toggle preview | | Ctrl-U | Clear query and filter | | Ctrl-Backspace | Delete the last query word | | ? | Show active keybindings | | Esc / Ctrl-C | Back or close |

Status glyphs follow Herdr's prefix+g visual language: ◉ blocked/attention, animated Braille spinner working, ● idle, ✓ done, and ○ unknown. Diamond color priority is marked yellow, current accent/blue, then previous red. Selection uses →, and source trees use ▾, ├─, and └─ markers.

On the initial unfiltered view, the previous workspace stays first, followed by marked items and then the normal source order.

Structured search narrows large result sets:

!claude          # agent name
@idle            # agent workspace/status
@Dotfiles        # agent workspace label or id
/dotfiles        # cwd/path

Set vimmode = true for normal-mode j/k, source keys, and / search. All source shortcuts can be remapped through [picker.filterkeys].

Power moves

Close an open directory

Select an open or agent entry, or a project, root, or zoxide entry that matches an open workspace, then press Ctrl-X. Navigator closes that workspace and refreshes the list.

Navigator refuses to close the workspace that owns the picker; switch away first. Directories that are not open and server, session, quick-action, or plugin entries are left unchanged.

Jump Back

Navigator remembers the workspace left by a successful local navigation. Bind the dedicated action for tmux-style current/previous toggling:

[[keys.command]]
key = "prefix+l"
type = "plugin_action"
command = "herdr-navigator.jump-back"
description = "jump to previous workspace"

The previous workspace can also stay pinned at the top of the initial picker view:

[jump_back]
Record local workspace transitions and enable the action.
enabled = true
Pin the previous workspace only while the picker is unfiltered.
pin_previous = true

If the previous workspace was closed, the next Jump Back clears the stale state and reports it.

Persistent side pane

Keep Navigator beside your work:

herdr plugin action invoke herdr-navigator.open-side

The action opens the side pane, focuses it when it already exists, and closes it when invoked while focused. Unlike the overlay, the side pane stays open after Enter.

Optional binding:

[[keys.command]]
key = "prefix+shift+t"
type = "plugin_action"
command = "herdr-navigator.open-side"
description = "navigator side pane"

Configuration

Navigator writes a fully commented config on first run:

herdr plugin config-dir herdr-navigator

See examples/default-config.toml for every option and its behavior. Common customizations:

[picker]
reuse_existing = true
create_missing = true
prefixworkspacelabels = true # set false to keep new labels plain
engine = "nucleo" # nucleo | skim | simple
source_order = ["workspace", "agent", "project", "session", "zoxide", "root", "server", "quick", "plugin"]
sourcepriorityboost = 5
agent_sort = "herdr" # herdr | priority | spaces
preview = true
detailed_rows = true # source-aware Herdr-style result rows
check_updates = true # daily background release check
directory_template = "default.toml" # Herdr Plus project file
directorytemplatekey = "alt-enter" # or ctrl-g / ctrl-t
vim_mode = false
[notifications] enabled = true audio = false # set true to enable sound sound = "default" # default | custom custom_sound = "" # Example: "~/sounds/navigator.wav"
[theme] 
Optional Navigator base palette: catppuccin, dracula, nord, tokyo-night, etc.
 
name = "dracula"
 
Inherit Herdr's static [theme.custom] tokens when available.
 inherit_herdr = true 
Navigator custom tokens have the highest precedence.
 
[theme.custom]
 
accent = "#ff00ff"

[sources] open_workspaces = true agents = true herdrplusprojects = true herdrplusquick_actions = true sessions = true servers = true zoxide = true roots = true
[[roots]] path = "~/workspace" max_depth = 3

Useful config surfaces:

• picker.detailed_rows enables source-aware rows: right-aligned metadata for most sources and a full-path second line only for zoxide/root.
• picker.check_updates checks GitHub releases in the background at most daily and shows ↑ vX.Y.Z available · F5 update; press F5, confirm, and Navigator installs that release through Herdr. Failures stay silent until an update is requested.
• picker.prefixworkspacelabels defaults to true and prefixes newly created workspace labels with project: or dir:. Set it to false for plain labels; Navigator still persists the workspace kind.
• picker.directorytemplate = "default.toml" reuses that Herdr Plus project file from its projects/ config directory. Enter keeps normal reuse/create behavior. picker.directorytemplatekey defaults to alt-enter and also accepts Ctrl forms such as ctrl-g; the shortcut always applies all template tabs, panes, labels, and commands using the selected directory instead of the template's workingdir, creating the workspace or appending fresh template tabs.
• [notifications] can disable notifications entirely or use Herdr's default sounds, no sound, or a custom audio file.
• [picker.filter_keys] remaps source shortcuts.
• [[agent_aliases]] adds memorable search terms without renaming Herdr panes.
• [sessions] controls local sessions and manual remote targets.
• [theme] can select a supported Navigator palette with theme.name. With inherit_herdr = true, Navigator uses Herdr's configured palette when theme.name is unset. If Navigator selects the base palette, inherited Herdr [theme.custom] tokens are applied next, then Navigator [theme.custom] tokens win. Missing or invalid inherited config falls back to Catppuccin; disabled inheritance with no Navigator name falls back to One Light.
• [[integrations]] adds external command/JSON sources.

Add your own source

A tool only needs a list command and an open command:

[[integrations]]
id = "bookmarks"
label = "Bookmarks"
enabled = true
collect = "bookmarks list --json"
open = "bookmarks open {{id}}"
notify_success = true
notify_error = true

collect prints a JSON array:

[{"id":"abc","title":"Item","subtitle":"Info","path":"/tmp","kind":"bookmark"}]

Navigator shell-quotes {{id}}, {{title}}, {{subtitle}}, {{path}}, and {{kind}} before running open. See docs/plugin-integrations.md for the full contract.

Requirements

• Herdr 0.7.3 or newer
• Linux or macOS
• Optional: zoxide for directory history
• Optional: Herdr Plus for project templates and Quick Actions
• Rust stable + Cargo only when building from source

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

Troubleshooting

Check that Herdr sees the plugin and its actions:

herdr plugin list
herdr plugin action list --plugin herdr-navigator

Inspect every collected candidate without opening the TUI:

./target/release/herdr-navigator list

If a keybinding does nothing, verify the action ID and reload config:

rg "herdr-navigator.open" ~/.config/herdr/config.toml
herdr server reload-config

Optional sources can be checked independently:

zoxide query -l
find ~/.config/herdr/plugins/config/cloudmanic.herdr-plus/projects -name '*.toml'

Project docs

• docs/roadmap.md — roadmap and scope boundaries
• docs/architecture.md — runtime flow and design
• docs/integrations.md — Herdr/plugin integration patterns
• docs/plugin-integrations.md — command/JSON contract
• CHANGELOG.md — released and unreleased changes
• CONTRIBUTING.md — development workflow