Herdr Plugin

herdr plugin

clauth ships a plugin for herdr that does two things: it opens the clauth dashboard in a popup over whatever you were doing, and it labels every herdr pane with the account that pane is spending.

Requires herdr 0.8.0 or newer, clauth on PATH, and Linux or macOS. The entrypoints are POSIX shell scripts, so the manifest declares those two platforms; herdr on Windows is preview-only anyway.

Install

clauth herdr install

One command for the whole setup. It runs herdr's own installer, passing herdr's preview of every command the plugin would run as you straight through, then adds the two things a herdr plugin cannot declare for itself: the key that opens the dashboard, and the sidebar row that renders the pane tag. Both land in your herdr config.toml, appended after a diff and a [y/N], and herdr validates the result before anything is written.

Run it a second time and it adds nothing. Run it from a clauth checkout and it links the local herdr-plugin/ directory instead of fetching the published one, so an edit is live on the next open.

Flag	Effect
--key <spec>	the key that opens the dashboard, in herdr's own binding syntax; default prefix+a
--no-config	install the plugin, leave config.toml alone, and print the blocks to paste
--yes	skip both prompts, herdr's install preview included; required on a non-TTY stdin

HERDR_CONFIG_PATH overrides which config file gets written, matching how herdr itself reads that variable.

To install by hand instead, run herdr plugin install uwuclxdy/clauth/herdr-plugin and paste the two blocks from the plugin README.

Uninstall

clauth herdr uninstall

Removes the plugin from herdr and drops the config blocks clauth added, as one operation behind one confirm. Declining leaves both halves exactly as they were. --no-config removes only the plugin; --yes skips the prompt.

It only removes blocks clauth marked as its own, so anything you wrote yourself stays, including edits inside those blocks' tables. If the plugin is already gone it says so and still cleans the config, which is the state a half-finished install leaves behind.

Actions

Action	Qualified id	What it does
Open clauth	clauth.open	the clauth dashboard in a popup; quit it with q, same as anywhere else
Show this pane's clauth account	clauth.which	re-reads the account the focused pane burns and republishes it as pane metadata

There is no account picker. Switching is a keystroke inside the dashboard, so a second switch surface would only know less than the first.

herdr allows one popup per session, so pressing the open key with clauth already up does nothing rather than reporting an error.

The key

A herdr plugin cannot declare a keybinding, so that line lives in your own herdr config.toml and nothing happens until it is there. clauth herdr install writes it:

[[keys.command]]
key = "prefix+a"
type = "plugin_action"
command = "clauth.open"
description = "clauth accounts"

command takes the qualified action id from the table above. prefix+ is herdr's own leader. Without a binding the actions are still reachable from herdr's action menu and from herdr plugin action invoke clauth.open.

The pane tag

Every herdr pane running Claude Code spends some account, and which one is invisible from the pane itself. The plugin hooks agent detection and publishes the answer as pane metadata under the name clauth.

It refreshes on every agent status change, so a clauth start --with-fallback session that moves onto the next chain member stops naming the account it left. herdr detects other agents too, and a pane running one of those is left untagged rather than labelled with an account it never touches.

herdr renders a reported value only where your own agent-row template asks for it, so the tag stays invisible until $clauth is in a row. clauth herdr install adds this one; Claude Code panes take the rows_by_agent template rather than the generic rows:

[ui.sidebar.agents.rows_by_agent]
claude = [["state_icon", "workspace", "tab"], ["terminal_title_stripped"], ["agent", "$clauth"]]

That reads claude · D1 in the sidebar for a pane started as clauth start D1. A pane running Claude Code some other way reports whichever account owns the global credentials. Point CLAUDE_CONFIG_DIR somewhere else yourself and the tag stops matching what that pane spends.

Checking it from the TUI

The dashboard's Plugin tab carries a herdr row, shown only if herdr is installed. It reports the herdr version, whether the plugin is linked or installed and whether it is enabled, the key you bound and its spelling, and whether the sidebar row is templated. A registry entry whose checkout has been moved or deleted reads as danger, since herdr keeps the entry and the plugin cannot run.

f on that row appends whichever of the keybinding and the sidebar row is missing, behind a confirm that defaults to cancel. It is the same write clauth herdr install performs, so it is the repair for a config edited by hand since. If your config spells one of those tables in a way clauth cannot extend by appending, it says so and leaves that half to you rather than guessing.

There is deliberately no "newer version available" check. herdr 0.8.0 ships no plugin update, and re-running clauth herdr install already is the refresh path.

What this plugin cannot do, by design of herdr's plugin v1

Plugin UI is pane-scoped. herdr documents runtime action registration and native non-terminal plugin UI as outside plugin v1, so none of this is a missing feature here:

• no button or row beside the sidebar spaces list, and no status-bar item
• no menu outside a pane
• no mouse binding of any kind: herdr's key parser rejects mouse tokens, and the only click routed to a plugin is a Control-click on a URL matching a link_handlers pattern
• no click-outside dismiss; a popup holds every keystroke, Esc included, until its command exits