--- title: "Best Herdr Plugins (2026): 10 Vetted Picks Worth Installing" description: "The best Herdr plugins worth installing in 2026: 10 vetted picks for agent review, usage and remote control, plus how to install and vet the marketplace." date: 2026-10-08 categories: ["ai"] tags: ["herdr","plugins","terminal"] --- import Button from "@components/widgets/Button.astro"; import Notice from "@components/widgets/Notice.astro"; import ListCheck from "@components/widgets/ListCheck.astro"; import Accordion from "@components/widgets/Accordion.astro"; import Tabs from "@components/widgets/Tabs.astro"; import Tab from "@components/widgets/Tab.astro"; import YouTubeEmbed from "@components/widgets/YouTubeEmbed.astro"; The Herdr plugin marketplace is young, huge, and completely unreviewed: roughly 1,000+ indexed plugins and about 1,500 repos tagged `herdr-plugin` on GitHub as of 2026-10-08. A plugin runs as your user with your full environment, so installing blind is a bad idea. What follows is my cut of the best Herdr plugins worth installing, with the install/pin/verify commands, plus the vetting workflow for the rest of the Herdr plugin marketplace. If you are new to the runtime itself, read [our Herdr review (open-source agent multiplexer)](/herdr-agent-multiplexer/) first, then check the [best AI coding tools and agents in 2026](/ai-coding-tools/) that these plugins observe. ## What are Herdr plugins? A Herdr plugin is a directory with a `herdr-plugin.toml` manifest plus commands Herdr launches as argv arrays. That is the whole model. There is no SDK and no restricted API surface: the entire `herdr` CLI is the plugin API, and plugins call back through `HERDR_BIN_PATH`, which works the same over Unix sockets and Windows named pipes. Any language works, because Herdr just execs what the manifest declares: Bash, JavaScript, Lua, Rust, Go, Python, PowerShell. The Herdr plugin marketplace at `herdr.dev/plugins` is not a catalog anyone has reviewed. It is an automatic index of public GitHub repositories tagged with `herdr-plugin`, refreshed every 30 minutes. Forks, archived repos, and repos whose manifests fail to parse are excluded. Everything else shows up. The official docs put it plainly: "A plugin is ordinary code that runs on your machine." Herdr validates the manifest fields and nothing else. It "does not review or sandbox plugin code." A plugin runs as your user, with your environment variables and your full CLI access. Vetting is your job, and the checklist below is the mitigation. ![Herdr plugin architecture diagram: manifest sections, argv commands, injected runtime environment variables, and callbacks through the herdr CLI](../../assets/images/26/10/herdr-plugin-anatomy.webp) The manifest is the contract. Required fields are `id`, `name`, `version`, and `min_herdr_version` (the plugin API exists since herdr 0.7.0, and Herdr refuses to install a plugin that demands a newer binary than the one you run). Optional sections cover the interesting parts: `[[build]]` compiles things on GitHub installs, `[[startup]]` runs one-shot init after session restore and re-runs on live handoff, `[[actions]]` are named commands you can invoke or bind to keys, `[[events]]` fire on things like `on = "worktree.created"`, `[[panes]]` place a UI (overlay by default, or `popup`, `split`, `tab`, `zoomed`), and `[[link_handlers]]` turn Ctrl+click on a URL into an action via a Rust regex. At runtime Herdr injects `HERDR_SOCKET_PATH`, `HERDR_BIN_PATH`, `HERDR_ENV=1`, `HERDR_PLUGIN_ID`, `HERDR_PLUGIN_ROOT`, `HERDR_PLUGIN_CONFIG_DIR`, `HERDR_PLUGIN_STATE_DIR`, and `HERDR_PLUGIN_CONTEXT_JSON`. Remember one rule about those paths: `HERDR_PLUGIN_ROOT` is a managed checkout that a reinstall replaces. Never store credentials there. Config and state dirs are yours to own. Scale matters for how you browse. The GitHub topic page lists about 1,500 public repositories as of 2026-10-08, and that count includes dotfiles collections and tools cross-tagged from other ecosystems. The curated index on herdr.dev shows only repos with parseable manifests on the default branch, which puts the real marketplace at roughly 1,000+ entries. Discovery is either the index or the GitHub topic search, the same way you would browse [top AI GitHub repos worth starring](/top-ai-github-repos/) and filter hard. Cost check before we continue: everything in this article is free and local. No account, no GPU, no database, no subscription. The only optional spend is a small VPS if you want agents running 24/7, and I cover that at the end. That is what most plugin coverage looks like: enthusiasm, no commands, no trust workflow. The picks below are the vetted, command-first version. ## How to install Herdr plugins the safe way Installing Herdr plugins is one command. Installing them without regret takes five minutes of reading first. The operator flow is: prerequisites, vet (the full checklist is its own section below), install with preview, pin the revision you reviewed, verify, and know the rollback path. ### Prerequisites (what you need) Herdr 0.7.0 or newer, because that is when the plugin API landed. Individual plugins can demand more: herdr-reviewr needs >= 0.7.5, and the herdr-web-ui installer expects 0.9.0+. Git, because `plugin install` clones a repository. And whatever toolchain the plugin builds with: node or bun for TypeScript plugins, Go for the herdr-plus and tsk crowd, cargo for the Rust TUIs. Herdr does not install toolchains for you. A missing `cargo` shows up as a failed build step that aborts registration. ### Install with preview, pin a revision 1. Browse the index at https://herdr.dev/plugins or search GitHub for `topic:herdr-plugin`. 2. Open the repo and read `herdr-plugin.toml` before anything else. If the commands look wrong, stop there. 3. Run `herdr plugin install owner/repo[/subdir]`. In an interactive terminal Herdr shows a preview of the source and the commands it is about to run. Read it. **Never pass `--yes` on a first install.** 4. Pin what you reviewed: `herdr plugin install owner/repo --ref v1.2.0`. The pin is your rollback anchor. 5. Build commands run only on GitHub installs. A build failure aborts registration, and editing the manifest after the preview aborts the install. Both are features. For local development, `herdr plugin link /path` registers a directory and skips builds entirely. ```bash # install with the interactive preview herdr plugin install persiyanov/herdr-reviewr # install the exact revision you reviewed herdr plugin install persiyanov/herdr-reviewr --ref v1.2.0 # local development: register a directory, no build step herdr plugin link /home/you/src/my-herdr-plugin ``` ```bash # one-time install of herdr itself curl -fsSL https://herdr.dev/install.sh | sh herdr --version # expect >= 0.7.0 git --version herdr plugin install owner/repo ``` ```powershell irm https://herdr.dev/install.ps1 | iex herdr --version herdr plugin install owner/repo ``` On Windows, build/action/event commands resolve `PATHEXT` shims, so `npm` and `bun` correctly become `npm.cmd` and `bun.cmd`. Pane commands must be valid Windows argv; do not paste Unix shell syntax into a `command` array. Plugin v1 has no `herdr plugin update`. "Updating" means re-running `herdr plugin install owner/repo` (optionally with a new `--ref`), and that **replaces the managed checkout**. Anything you left in `HERDR_PLUGIN_ROOT` is wiped. Keep secrets and settings in `HERDR_PLUGIN_CONFIG_DIR`, which survives reinstalls and uninstalls. ### Verify it worked After every install, confirm registration and a clean first run: ```bash herdr plugin list --json # registered + enabled, with ids herdr plugin action list --plugin plugin.id # what actions exist herdr plugin action invoke plugin.id.action # run one once herdr plugin log list --plugin plugin.id --limit 20 ``` Open the plugin's pane or action once and expect normal output in the logs with exit code 0. What "broken" looks like: the plugin missing from `plugin list`, a non-zero exit in `plugin log list`, or an action that hangs because its toolchain or a config file is missing. To bind an action to a key, add it to `~/.config/herdr/config.toml` and reload: ```toml [[keys.command]] key = "prefix+l" type = "plugin_action" command = "example.layout.apply" description = "apply layout" ``` ```bash herdr server reload-config ``` ### Rollback / undo ```bash herdr plugin disable ID # keep it, stop it running herdr plugin enable ID herdr plugin uninstall ID # removes the managed checkout herdr plugin unlink ID # local dev deregistration ``` `uninstall` removes the managed checkout but leaves the config and state dirs in place, which is your recovery path if you uninstall by mistake. Two quirks to know: installing over a linked plugin is refused, so `unlink` first; and on 0.7.3, plugins registered only inside a named session need to be re-linked or reinstalled. Failure modes in this section: a build abort with capped stdout/stderr is almost always a missing `cargo`/`npm`/`go`, install the toolchain and retry. A refused install over a local dir means you hit the linked-plugin rule. An abort after the preview means the manifest changed between preview and confirm, which is Herdr refusing to run code you did not see. ## The 10 best Herdr plugins worth installing Ten picks, grouped by the job they do. Star counts are 2026-10-08 snapshots, not trust scores. Every install command is fully qualified `owner/repo` on purpose, because name collisions are real in this marketplace. ![Herdr marketplace funnel diagram: over a thousand plugins grouped into seven jobs with the ten recommended picks listed beside each job](../../assets/images/26/10/herdr-marketplace-by-job.webp) ### Review the agent's diff (herdr-reviewr) `persiyanov/herdr-reviewr` (804 stars) opens the agent's diff in a terminal pane and sends line comments back to Claude Code, Codex, OpenCode, and Pi. Rust, with prebuilt binaries so there is no cargo step on install. It wants herdr >= 0.7.5 and runs on macOS and Linux. It closes the gap that matters once an agent writes code: the one between "it wrote code" and "you read it." This is the killer use case for Herdr plugins in general, because the review loop lives beside the agent instead of in a browser tab you forget to check. ```bash herdr plugin install persiyanov/herdr-reviewr ``` ![herdr-reviewr running inside the Herdr TUI: a git diff pane with a line comment queued to send back to the agent](../../assets/images/26/10/herdr-reviewr-ui.webp) Trust note: small Rust surface, manifest declares the usual actions and panes, no surprises in the command arrays beyond the review binary itself. Verify by opening the review pane once on a repo with uncommitted changes and confirming the diff renders, then leave a test line comment and watch it arrive in the agent's input. What "broken" looks like: an empty diff pane on a dirty working tree, which usually means the plugin is not pointed at the right workspace tab. If you want lighter, `jhochenbaum/herdr-hunk-diff` (143 stars) does hunk-based review with inline comments and fewer moving parts. Install it the same way: `herdr plugin install jhochenbaum/herdr-hunk-diff`. `plannotator/herdr-annotate` is the annotate-anything cousin if your feedback loop is about terminal text in general, not just diffs. ### See what the agent touched (herdr-file-viewer) `smarzban/herdr-file-viewer` (636 stars) is a git-aware, read-only file tree TUI: tree plus content, working-tree diffs, rendered markdown, syntax highlighting. Read-only is a feature when the agent is the one writing files. You look, it writes, and you cannot fat-finger an edit in the viewer. ```bash herdr plugin install smarzban/herdr-file-viewer ``` ![herdr-file-viewer full-screen: file tree on the left, rendered file content with syntax highlighting on the right](../../assets/images/26/10/herdr-file-viewer-ui.webp) Trust note: presentation-layer plugin, the risky part is whatever it execs to read git state. Verify by opening the tree pane and confirming the working-tree diff shows the agent's last change. If the tree renders but diffs stay empty, check that you opened the pane in the same workspace tab as the repo; the plugin reads the git state of its own pane context. If you want a write-capable VS Code-style explorer instead, `alexarthurs/herdr-sidebar` (424 stars) gives you file explorer, git source control, diffs, and AI commit messages. Note the difference before you install: it can change your repo, herdr-file-viewer cannot. ![alexarthurs/herdr-sidebar: file explorer, source control panel, and agent panes inside the Herdr sidebar](../../assets/images/26/10/herdr-sidebar-ui.webp) ### Watch agents and track spend (zoetrope, herdr-agent-usage) `furkankly/zoetrope` (978 stars) draws a live flow graph of a Claude Code or Codex session, in the terminal or in a browser. Rust and ratatui. When you have three agents running and need to know what one is doing right now, this is the pane you open. ```bash herdr plugin install furkankly/zoetrope ``` ![zoetrope's live flow graph: agent nodes with running/idle state flowing through a session](../../assets/images/26/10/herdr-zoetrope-graph.webp) `levi-qiao/herdr-agent-usage` (168 stars) shows credential-scoped AI usage, context, and cache for Claude, Codex, Grok, Devin, Cursor, and friends, in a sidebar or statusline. Token cost is the real bill in an agent stack. The plugins only observe it, but observing it is the difference between a fun weekend and a surprise invoice. ```bash herdr plugin install levi-qiao/herdr-agent-usage ``` ![herdr-agent-usage sidebar: per-agent context, API and weekly-usage gauges grouped by project](../../assets/images/26/10/herdr-agent-usage-gauges.webp) There is a different repo called `senna-lang/herdr-agent-usage` (47 stars) that does context meters and rate limits. Same plugin name, different code, different author. Always install by fully qualified `owner/repo` and write down which one you got. The same trap exists with auto-titles and browser plugins; see the gotchas section. Verify zoetrope by opening its pane during a live agent session and expecting the flow graph to update. Verify herdr-agent-usage against one known account and confirm the numbers roughly match the provider's own dashboard. `hhdebb/herdr-radar` (154 stars) is the alternative if what you need is "who is working, who is waiting on me," grouped by project with idle sessions fading out. ```bash herdr plugin install hhdebb/herdr-radar ``` ![herdr-radar sidebar in light and dark themes: agents grouped by project with working/idle state](../../assets/images/26/10/herdr-radar.webp) ### Workspace bootstrap and navigation (herdr-plus, herdr-auto-title, herdr-navigator) `cloudmanic/herdr-plus` (345 stars) is the one plugin here with its own website for a reason. Projects rebuilds an entire workspace from a single TOML file you own: tabs, splits, startup commands. Quick Actions is a fuzzy launcher that works in any tab, with per-repo `.herdr-plus/` action files. Go binary, own docs at herdrplus.com, Homebrew tap if you want it that way. ```bash herdr plugin install cloudmanic/herdr-plus ``` ![herdr-plus Projects picker: a fuzzy list of workspaces grouped by project, opened over a pane](../../assets/images/26/10/herdr-plus-projects.webp) The site advertises default keys at prefix + up/down after binding. Confirm the binding in `~/.config/herdr/config.toml` if it does not respond, then `herdr server reload-config`. Verify by defining a two-tab project TOML, restarting, and confirming the layout comes back. The "TOML you own" part is what sold me on this one: no hidden state, no database, the layout lives in a file you can commit to your dotfiles and hand-edit at 2am when a pane is in the wrong place. `kryptamine/herdr-auto-title` (238 stars) auto-names tabs and panes from git branch, terminal activity, and Claude Code sessions. At 10+ panes this is not a nicety, it is how you find anything. ```bash herdr plugin install kryptamine/herdr-auto-title ``` ![herdr-auto-title: tab bar with generated names like claude-1:oauth and git-branch titles instead of generic pane numbers](../../assets/images/26/10/herdr-auto-title-ui.webp) `thanhdat77/herdr-navigator` (178 stars) is one fuzzy navigator for workspaces, agents, projects, remotes, and directories. If you already live in a fuzzy jumper like [smarter terminal navigation with zoxide](/zoxide/), this is the same muscle memory applied to Herdr's object model. ```bash herdr plugin install thanhdat77/herdr-navigator ``` ![herdr-navigator's fuzzy finder popup matching workspaces, agents, projects and directories over a live pane](../../assets/images/26/10/herdr-navigator-fuzzy.webp) One mention for the audit-minded: `qu8n/herdr-automatic-rename` (209 stars) is the plain-Shell twin of auto-title and probably the easiest plugin in this whole article to read end-to-end. Good "first plugin you vet" candidate. ### Crash recovery and plugin management (herdr-resurrect, herdr-plugin-manager) `ntindle/herdr-resurrect` (37 stars) is tmux-resurrect for herdr: it snapshots workspaces, tabs, panes, cwd, programs, and agents, and restores them after a crash or reboot. The star count is low, the value is not. Losing a 12-pane agent farm to a reboot is a bad afternoon. Snapshots trigger on the events the plugin declares and restore through the same herdr CLI everything else uses, so there is no separate daemon to babysit. ```bash herdr plugin install ntindle/herdr-resurrect ``` `speardragon/herdr-plugin-manager` (51 stars) manages installed plugins from a popup: install, enable, uninstall, browse the marketplace. Default binding is `prefix+p`. ```bash herdr plugin install speardragon/herdr-plugin-manager ``` ![herdr-plugin-manager popup: installed plugin list with per-plugin actions and a marketplace browser sorted by stars](../../assets/images/26/10/herdr-plugin-manager.webp) Footgun: popups are singleton session resources. They have no pane ID and no lifecycle events, and they return `ui_busy` if a Settings or Copy-mode modal is open. That is Herdr, not a broken plugin. Snapshots are not backups. Version your `config.toml` and each plugin's `HERDR_PLUGIN_CONFIG_DIR` contents in git or [self-hosted backups with Restic](/pluton-self-hosted-backup/). Plugin code itself re-installs from pinned refs, so it does not need to live in your backup set. ### Reach your agents from your phone (collie) `AltanS/collie` (1,256 stars) is a self-hosted PWA that drives Claude Code, Pi, Codex, and OpenCode running inside Herdr, tmux, or zellij from your phone. Push alerts, Tailscale by default, no app store involved. It is the most popular remote client in the plugin space and the one I would pick if the machine stays at home behind Tailscale. ```bash herdr plugin install AltanS/collie ``` ![Collie's phone UI: agent inbox grouped by project with needs-you, unseen, working, done and idle counts](../../assets/images/26/10/collie-dashboard.webp) These plugins expose live terminal and agent sessions over tunnels, relays, or bots. Prefer Tailscale (free tier) or a Cloudflare Tunnel over any open inbound port. Treat relay tokens like secrets. And recheck licenses before you build on these repos: `0cv/herdr-mobile-relay` and `dcolinmorgan/herdr-remote` both show NOASSERTION licenses as of 2026-10-08. If collie does not fit, `0cv/herdr-mobile-relay` (287 stars) does mobile web plus QR setup and multi-computer relays via Cloudflare, with the license caveat above. `devswha/herdr-web-ui` (284 stars) is the browser-first option: chat and a live terminal per pane, remote machines over SSH, web push. For the full remote-client picture (web UIs, phone apps, desktop apps) see the companion piece on the [best Herdr clients](/best-herdr-clients/). Some links in this guide are affiliate links. If you buy through them, we may earn a small commission at no extra cost to you. This helps us keep testing and updating these recommendations. If the machine running your agents has to stay up 24/7, a 2-4 GB [Hetzner Cloud](https://go.bitdoze.com/hetzner) box at roughly 4-8 EUR/month is plenty; no GPU involved. A budget [Hostinger VPS](https://go.bitdoze.com/hostinger-vps) with NVMe/EPYC specs works at the same tier. For the full always-on setup, including push approvals and the mosh footguns, see how to [run agents 24/7 on a VPS and control them from your phone](/control-ai-agents-from-phone-moshi-herdr/). ### Fun picks (herdr-ohmyzsh, herdr-flock) The fun drawer, not counted in the ten. `robbyrussell/herdr-ohmyzsh` (84 stars) is by the Oh My Zsh author himself: slow commands listed in a sidebar, done notifications, and a reload of Oh My Zsh across all idle panes. If you already run the [best Oh My Zsh plugins](/best-oh-my-zsh-plugins/), this is the Herdr-side companion. ```bash herdr plugin install robbyrussell/herdr-ohmyzsh ``` `ragamo/herdr-flock` (41 stars) renders your agents as pixel-art sheep on a farm. It is useless and it is delightful, which is the correct ratio for a plugin named after sheep. ```bash herdr plugin install ragamo/herdr-flock ``` ![herdr-flock: pixel-art sheep wandering a farm field inside a Herdr pane, one sheep per agent](../../assets/images/26/10/herdr-flock-sheep.webp) ## How to vet a Herdr plugin in 5 minutes ![Vetting flowchart for Herdr plugins: repository, manifest, commands, scripts, author history, then pin and install, with walk-away exits at each gate](../../assets/images/26/10/herdr-plugin-vetting-flow.webp) The marketplace page itself says "Listings aren't reviewed by Herdr, so install at your own discretion." The interactive preview dialog is the only gate in the entire system. Here is the checklist I run before that dialog ever appears. herdr.dev/plugins is an automatic index. Nobody at Herdr has read these repos. Five minutes of reading beats a bad install, and re-vetting is only needed when you move the pin. 1. **Read `herdr-plugin.toml`.** Every `[[build]]`, `[[startup]]`, `[[actions]]`, `[[events]]`, and `[[link_handlers]]` entry is code that will run on your machine. Check the required fields (`id`, `name`, `version`, `min_herdr_version`) and read every `command` array before you look at anything else. 2. **Read every command as argv.** There is no shell expansion unless the command starts a shell. Quoting surprises hide in `["bash", "-c", "..."]` wrappers, not in `["node", "index.js"]`. 3. **Skim the scripts.** Anything that touches `~/.aws`, `~/.ssh`, `.env` files, or agent credential directories deserves a full read, not a skim. That is the difference between a UI plugin and something that can exfiltrate your tokens. 4. **Check the author and repo history.** Stars are not trust, and a topic tag is not a guarantee the thing even installs as a Herdr plugin. Fresh accounts plus obfuscated build steps is a walk-away. If you want a gentle first vet, `qu8n/herdr-automatic-rename` and `tdi/herdr-worktree-setup` are small and readable end-to-end. 5. **Pin the reviewed tag.** `herdr plugin install owner/repo --ref vX.Y.Z`. Never `--yes` on a first install. If the manifest changes after the preview, Herdr aborts; leave it aborted and go re-read. Cost note: vetting is 5 minutes once per plugin. Reinstalling from a pinned ref is the update path, and re-vetting is only the delta between the old tag and the new one. For remote-relay plugins specifically, the threat model is your whole terminal. If you are exposing a box at all, read [hardening an exposed server](/bsi-security-report-docker-ufw/) before you expose a relay. ## Herdr plugins vs tmux: what's different The "Herdr vs tmux" question comes down to plugins more than panes. If you only want panes and scrollback, tmux is still fine and it will still be fine in five years. | Capability | tmux | Herdr plugins | |---|---|---| | Plugin distribution | Copy shell scripts into `.tmux.conf` territory | `herdr plugin install owner/repo` from a marketplace index | | Plugin definition | Ad hoc shell functions | `herdr-plugin.toml` manifest with build/startup/actions/events/panes | | API surface | tmux commands | The entire herdr CLI via `HERDR_BIN_PATH` | | Events | Hooks you wire yourself | Declarative `[[events]]` like `on = "worktree.created"` | | URL handling | Manual | `[[link_handlers]]` with Rust regex, Ctrl+click dispatch | | Sandboxing | None | None | | Update channel | Whatever the plugin's README says | None in v1, reinstall to refresh | | Review process | None | None, it is an automatic index | What Herdr gives you: manifest-declared argv commands, events, pane placement, link handlers, and keybinding integration in `~/.config/herdr/config.toml`. What it does not give you: sandboxing, managed storage (durable state is the plugin's own files), an update channel, or any review process. tmux's plugin scene is smaller and dumber, and that is also its safety story. My verdict: the plugin ecosystem is the reason to move when you are running agent CLIs, not the multiplexer part. tmux already multiplexes. Herdr's edge is that agent workflows like diff review, session graphs, and workspace bootstrap are one command away instead of a weekend of scripts. If your tmux setup is already a pile of custom shell and you run agents in it daily, migrating is worth a weekend. If you mostly run two shells and a log tail, tmux has fewer moving parts and nothing to vet. For the runtime comparison itself, see [our Herdr review (open-source agent multiplexer)](/herdr-agent-multiplexer/), which covers the tmux question in depth. And if what you are actually shopping is the multiplexer itself rather than the agent layer, [Superlogical Rex](/superlogical-rex/) is the new terminal-side option worth tracking. ## Gotchas nobody tells you These are the things that will bite you in the first month. 1. **No `plugin update` command.** Updates mean re-running `herdr plugin install`, which replaces the managed checkout. Anything in `HERDR_PLUGIN_ROOT` is gone. Keep secrets and settings in `HERDR_PLUGIN_CONFIG_DIR` and you can reinstall at will. 2. **Name collisions are real.** There are two `herdr-auto-title` repos (kryptamine 238 stars vs sh1ma 51 stars), two `herdr-agent-usage` repos (levi-qiao 168 stars vs senna-lang 47 stars), and at least three browser-ish plugins (`ogulcancelik/herdr-browser` 357 stars, StructuPath 23 stars, plus `zenbu-labs/terminal-browser`). Fix: always use fully qualified `plugin.id.action`, and note the `owner/repo` you installed. 3. **Missing licenses.** `herdr-remote` and `herdr-mobile-relay` both show NOASSERTION. `pi-extensible-workflows` has no license field at all. Do not build on these in anything you get paid for without a license you can live with. 4. **`ui_busy` on popups.** Popups are singleton session resources with no pane ID and no pane events. A Settings or Copy-mode modal blocks them. If a plugin's popup "does nothing," close your modals first. 5. **Keybinding collisions.** `[[keys.command]]` entries can shadow the built-in keymap. Pick unused keys and run `herdr server reload-config` after every edit, or nothing changes and you will blame the plugin. 6. **Startup hooks are not daemons.** `[[startup]]` is one-shot init that re-runs on live handoff. A plugin that abuses it as a supervisor will misbehave. If you write one, make the hook idempotent. 7. **Build failures abort install** with capped stdout and stderr. Almost always a missing toolchain. Install `cargo`/`npm`/`go`, retry, and read the capped log. 8. **0.7.x API churn.** This ecosystem is months old. Pin refs, expect `min_herdr_version` bumps, and treat every reinstall as a chance to re-read the manifest diff. Popular plugins still ship with name collisions, NOASSERTION licenses, and popup quirks. Stars tell you what other people installed, not what runs safely in your environment. Pair them with the 5-minute vet and pinned refs, and expect the 0.7.x API to move under you. ## Write your own plugin in 20 lines Most of what plugins do is: run a command, show a pane, call the herdr CLI back. Here is a minimal manifest. ```toml # herdr-plugin.toml id = "example.workspace-tools" name = "Workspace Tools" version = "0.1.0" min_herdr_version = "0.7.0" platforms = ["linux", "macos", "windows"] [[actions]] id = "list-workspaces" title = "List workspaces" contexts = ["workspace"] command = ["node", "index.js"] ``` And the callback pattern. The whole CLI is the API: ```javascript // index.js const { spawnSync } = require("node:child_process"); const herdr = process.env.HERDR_BIN_PATH ?? "herdr"; const res = spawnSync(herdr, ["workspace", "list"], { encoding: "utf8" }); console.log(res.stdout); ``` Local dev loop: ```bash herdr plugin link /abs/path/to/plugin # register, no build commands run herdr plugin action invoke example.workspace-tools.list-workspaces herdr plugin log list --plugin example.workspace-tools --limit 20 herdr plugin unlink example.workspace-tools ``` Where state goes: `HERDR_PLUGIN_CONFIG_DIR` for settings and secrets, `HERDR_PLUGIN_STATE_DIR` for durable state. There is no managed storage API in v1, so the plugin writes its own files. And never write into `HERDR_PLUGIN_ROOT`; reinstall replaces it. Plugins versus skills, since people conflate them: plugins extend the terminal runtime (panes, events, keybindings). Skills extend the agent's context (instructions the model loads). Different layer, different file, different problem. If the problem is "the agent does not know how to do X," that is a skill, and [Agent Skills compared](/best-ai-skills-for-web-design/) is the right read.