[idea] Plugin API: contribute items to the workspace / worktree sidebar context menu

[wyattjoh]

idea / problem

When I right-click a worktree entry in the sidebar I get a fixed, hard-coded menu: Rename, Close, Delete worktree checkout. There is no way for a plugin to add entries to that menu.

As a plugin author building worktree management tooling I need a contextual surface to offer actions like "Copy worktree path". The checkout path is already known to Herdr (it places it under <worktrees.directory>/<repo>/<branch-slug>) but there is no way to surface it to my clipboard today without leaving Herdr or asking users to memorise an arbitrary keybinding.

Keybindings are the only current plugin trigger surface, but they are not discoverable, and they do not carry the clicked workspace/worktree as implicit context. A right-click on the exact entry a user is looking at is the natural place to offer workspace-scoped plugin actions.

requested change

Add a [[context_menu_items]] table to herdr-plugin.toml that lets plugins declare entries injected into the sidebar right-click menus for workspaces and worktrees.

Each item declares a label, which surface(s) it targets, and the action id to invoke. When the user clicks the item Herdr invokes the action exactly as it would for a keybinding-triggered action, and injects the same invocation context it already provides (workspace id, worktree path, branch name) as environment variables so the plugin command can act on what was right-clicked without any additional socket round-trips.

Minimal manifest sketch:

[[context_menu_items]]
id       = "copy-path"
label    = "Copy worktree path"
surfaces = ["worktree"]   # or ["workspace"], or both
action   = "copy-path"

The corresponding action entry stays unchanged. The plugin receives HERDR_WORKTREE_PATH (or equivalent) and can write to the clipboard via the OS, call back through HERDR_BIN_PATH, or do anything else a normal plugin action already can.

why you want this

The immediate use case is a "Copy worktree path" menu item for a worktree management plugin. One click, path on the clipboard. No keybinding to remember, no pane to open.

But the same mechanism unlocks a whole class of contextual worktree actions: running post-checkout setup scripts on a freshly created worktree, offering a teardown flow that goes beyond "Delete worktree checkout", or opening the path in another tool. All of these are naturally right-click actions because the user is already looking at the worktree entry when they want to act on it.

Context menus are the right UX here because they are discoverable (users find them by right-clicking, not by reading docs), contextual (the clicked item is the implicit target), and composable (multiple installed plugins can each contribute entries without conflicting). Keybindings are a poor substitute for this pattern.

[tdi]

I am highly supporting this for plugins - use cases are for example running a reviewer on space / agent or creating new wt from a gh PR.

[tdi]

Quick technical feasibility pass against the current codebase: yes, this is very doable, and it composes cleanly off three things that already exist.

1. Plugin action invocation already exists. invoke_plugin_action_from_keybind() runs a declared [[actions]] entry with workspace context. A context-menu trigger is the same flow with a different invocation_source.

2. The invocation context already carries the worktree. PluginInvocationContext injects workspace_id, workspace_cwd, and the full worktree snapshot (including checkout_path + branch). So a "Copy worktree path" action already has everything it needs — no new context plumbing. (Today the path only ships in HERDR_PLUGIN_CONTEXT_JSON; a dedicated HERDR_WORKTREE_PATH env var alongside HERDR_WORKSPACE_ID would be a one-line addition to match this proposal.)

3. The right-click context menu already exists. ContextMenuKind (Workspace / GitWorkspace / Tab / Pane), Mode::ContextMenu, render_context_menu, and dispatch via MouseAction::ContextMenu { menu, idx } are all in place. The right-click handler already knows the clicked ws_idx.

What would actually have to change:

• Manifest: a [[context_menu_items]] table (id, label, action) plus validation that each action references a declared action — this is the same validation pattern already used for [[link_handlers]].
• Menu items become dynamic: today ContextMenuState::items() returns a hardcoded &'static [&'static str] and dispatch matches by string label. That needs to become a computed list (built-in labels + appended plugin labels + a separator) so render and dispatch share one list.
• Dispatch branch: clicks on plugin-item indices route to a new invoke_plugin_action_from_context_menu(action_id, ws_idx).
• One correctness detail worth calling out: the existing keybind path builds context from the active workspace (current_plugin_context). For a context menu the context must come from the clicked entry — plugin_context_for_workspace(ws_idx) already exists for exactly this, so it's a straightforward swap, but it's the thing to get right.

One design suggestion: the proposed surfaces = ["worktree", "workspace"] field overlaps with the existing contexts: Vec<PluginActionContext> field on actions (Global | Workspace | Tab | Pane | Selection). Reusing contexts (where Workspace already covers both workspaces and worktree entries today) avoids two parallel gating mechanisms in the manifest.

No architectural changes, no runtime/client boundary concerns (menu = TUI presentation; action dispatch reuses the existing server invocation path). It's roughly one small refactor + six small additions, all following patterns already in the codebase.

[tdi]

@ogulcancelik is this something yuo could see added to plugin api ?

[ogulcancelik]

i'm working on a configurable sidebar for both agents and workspaces but it needs to wait a bit because it's a core change that would also needed to support multiclients.

[tdi]

@ogulcancelik awesome

[daviddwlee84]

Strong +1. A concrete use case beyond copy-path: a "Mark for review / unread" toggle on agent/workspace rows. I've prototyped it at the shell level with herdr pane report-metadata --source review --custom-status … (works today, orthogonal to agent state) plus a fuzzy picker over herdr pane list; the one missing piece is exactly what you describe — a discoverable, context-carrying right-click trigger (keybindings work but aren't discoverable and don't carry the clicked row). Reusing the existing contexts gating per @tdi's feasibility note sounds right.

[jgrizon]

Adding the missing half of @tdi's feasibility pass. He's right that invocation already works — the gap is on the render side, and it's structural.

The manifest contract is already shipped, and it's inert. PluginActionContext is:

// src/api/schema/plugins.rs:355
pub enum PluginActionContext { Global, Workspace, Tab, Pane, Selection }

That's one variant per context menu herdr has, plus selection. But contexts is only ever parsed (manifest.rs), stored, and echoed back by plugin.action.list (api/plugins/mod.rs:685) — nothing reads it to decide anything. Same for title: no code path draws it. And invocation_source is only ever set to startup, api, keybinding, link_click, cli — there is no menu path to set.

So a plugin author writes title = "..." and contexts = ["pane"] because the manifest asks for them, and neither field can ever have an effect. On 0.8.0 the only ways to fire an action are a plugin_action keybind or herdr plugin action invoke.

Why no plugin can work around it. Every menu is a compile-time array:

// src/app/state.rs
pub fn items(&self) -> &'static [&'static str] {
    ContextMenuKind::Tab { .. } => &["New tab", "Rename", "Close"],

&'static means the list is baked into the binary. There is no point at which herdr assembles a menu, so there is nowhere for a runtime-discovered action to go. That's the blocker — not the invocation plumbing.

Minimal shape of a fix: have items() return owned entries; on menu open, append plugin actions whose contexts match the menu kind; on click, dispatch anything that isn't a built-in through plugin.action.invoke with invocation_source = "menu" and the existing PluginInvocationContext (which already carries the clicked workspace/tab/pane and selected_text).

Demand is fragmented, which is probably why this reads smaller than it is: #1272, #1512, #1672, #1722, Q&A #1527 here, plus issues #1511, #1671, #1776, #1830 auto-closed to discussions.

I have this working locally on a v0.8.0 fork — menus built at runtime, entries dispatching through the API path. Happy to open a PR against the real design if a maintainer wants it; I'd rather match your intended shape than guess.

[jeffreyhaen]

+1, from a plugin user angle rather than a plugin-author one.

My case is deliberately boring: git pull / git push on the workspace row. One space per repo, the row already shows me the branch and that I'm ahead, and that row is exactly where my mouse already is. Right-click → Git pull is the whole feature.

What I have instead today is a plugin with a keybinding that opens a small pull/push/fetch picker in a pane. It works, but it acts on the focused workspace rather than the one I clicked, so I first focus the row, then recall the key. The mouse path is the natural one here and it's the only one that isn't available.

The manifest side already reads like it anticipates this — my actions declare contexts = ["workspace"], Herdr parses it happily, and then the value never surfaces anywhere. That mismatch is what sent me looking for a menu setting in the first place.

[xiaoyu2er]

+1. Same use case as @jeffreyhaen: one space per repo, and I'd like "Git pull" on the workspace right-click menu. contexts = ["workspace"] is already declared in plugin manifests but isn't read when the menu is built, so a plugin can't reach that menu today. A [[keys.command]] binding works, but it isn't discoverable from the mouse-first UI.