Herdr Palette

A Raycast/Linear-style command palette for Herdr, the terminal workspace manager for AI coding agents.

prefix+space opens a centered overlay that fuses every Herdr surface into one palette: keybindings, plugin actions, custom commands, workspaces, tabs, and agents. It defaults to a mnemonic tree view, toggles to a flat Raycast-style list with Ctrl-t, and dispatches safe rows with Enter.

┌ Herdr Palette · catppuccin ─────────────────────────┐
│View TREE   > split▏                                 │
│  ▾ Panes                                            │
│    ▾ Focus                                          │
│      • Previous pane  prefix+shift+tab  match       │
│    ▾ Layout                                         │
│      • Split vertical  prefix+v, prefix+|  match    │
│▶     • Split horizontal  prefix+minus  match        │
└─────────────────────────────────────────────────────┘

What it does

The palette is a read layer over the live Herdr server. It collects:

Tree mode preserves mnemonic group context from herdr-pretty-which. Flat list mode sorts by fuzzy score, dispatchability, source priority, then title.

Dispatch tiers

• Tier A — direct CLI: safe create/focus/split/zoom actions and plugin actions with fully resolved command[] arrays.
• Tier B — list + resolve + focus: previous/next workspace, tab, and agent cycles. The palette reads the live ordered list, finds the focused row, then focuses the neighbor.
• Reference-only: rows that are keybinding-only or need a target/prompt the palette cannot provide safely yet. These render greyed and ignore Enter.

Install

cargo install herdr-palette --locked

Herdr plugin support requires Herdr >= 0.7.0. After installing the binary, link the plugin manifest from this checkout or from your plugin manifest directory:

herdr plugin link .
herdr plugin pane open --plugin ramarivera.palette --entrypoint overlay --placement overlay --focus

For local development only:

cargo build --release
cargo install --path . --locked

The published crate depends on herdr-pretty-which from crates.io. A sibling checkout is only needed when developing both crates together.

Run

# Interactive overlay, when stdout is a TTY.
herdr-palette

# Start the overlay directly in shell mode.
herdr-palette --shell

# Snapshot to stdout for tests/screenshots/non-TTY.
herdr-palette --snapshot --query "split" --width 100 --height 30

# Diagnose which sources are contributing items.
herdr-palette --debug-kinds

# Print occupied chords from all collected key sources.
herdr-palette --debug-keys

Keybindings inside the palette

Shell mode runs a command with the login shell. When no shell command is running, Esc, Ctrl-c, Ctrl-d, or empty Enter closes the plugin pane.

Theming

Inherits your configured Herdr theme via Palette::from_theme: catppuccin, tokyo-night, dracula, nord, gruvbox, one-dark, solarized, kanagawa, and custom [[theme.custom]] overrides. The palette uses the same colors as herdr-pretty-which, so it matches the rest of the Herdr UI.

Herdr plugin manifest

herdr-plugin.toml declares the plugin so Herdr can discover and launch it:

id = "ramarivera.palette"

[[actions]]
id = "open"
title = "Open palette"
contexts = ["workspace", "tab", "pane", "global"]
command = [
  "herdr",
  "plugin",
  "pane",
  "open",
  "--plugin",
  "ramarivera.palette",
  "--entrypoint",
  "overlay",
  "--placement",
  "overlay",
  "--focus",
]

Bind it to a chord in your Herdr config:

[keys]
# e.g. open the palette with prefix+space
workspace_picker = "prefix+space"

Architecture

src/
├── main.rs      # CLI args and mode dispatch
├── source.rs    # collects sources into Vec<Item>
├── items.rs     # item constructors and tree metadata
├── dispatch.rs  # action-to-dispatch map and runner
└── tui.rs       # tree/list state, fuzzy filtering, render loop

The terminal restore path is guarded by drop guards, so a failure mid-loop never leaves your terminal in raw mode.

License

MIT