herdr Integration

herdr  is a terminal workspace manager for AI coding agents. It can back a workspace with a Git worktree so agents run in an isolated checkout. herdr manages terminals and workspaces, while AgentTeams acts as the governance layer for team conventions, plans, verification, and completion reporting.

MCP registration does not target herdr. herdr itself is not an MCP client, so it is not one of the agentteams mcp install --client values. Register the AgentTeams MCP server with the individual agents herdr launches (Claude Code, Codex, Cursor CLI, and so on) — running agentteams mcp install inside the worktree detects them. See MCP Integration.

Bootstrap a worktree

If the AgentTeams CLI is not installed, install it globally first:

npm install -g @agentteams/cli

herdr’s worktree create runs git worktree add underneath. So when the worktree bootstrap hook is installed on the main checkout, every new worktree herdr creates connects its conventions automatically. Nothing else is required.

Check for the hook — and install it if it is missing — from the main checkout root:

agentteams doctor --install-worktree-hook

Worktree bootstrap hook: ready means you are set. Without the flag, agentteams doctor leaves the hook uninstalled in a repository that has no linked worktree yet and reports Worktree bootstrap hook: skipped instead. Use the flag to set it up before creating the first worktree.

Where the hook cannot be used — a custom post-checkout hook already exists, or core.hooksPath points somewhere other than the default hooks directory — run this once per worktree from the worktree root instead:

agentteams init

In a linked Git worktree, this connects the existing AgentTeams configuration from the main checkout. The worktree’s .agentteams is a link rather than a copy, so convention updates made in the main checkout are visible in the worktree immediately.

Worktrees created with herdr are picked up by the Runner’s automatic worktree discovery like any other linked worktree. Discovery remains available when herdr events are not delivered. See Discovered RunnerBoxes.

Optional immediate lifecycle notifications

herdr has no repository-level worktree hook file. It uses plugin event hooks instead. AgentTeams publishes those hooks as a plugin in the public repository AgentTeamsRun/herdr , so you can enable them with a single install command instead of authoring a manifest yourself. The contract below was verified against herdr 0.8.0.

Prerequisites

• herdr 0.8.0 or newer. The manifest declares min_herdr_version = "0.8.0". Only 0.8.0 was verified; which command older versions reject, and with what message, was not checked.

• Run agentrunner init --token <token> first so the host has a daemon token.

• The repository the worktree belongs to needs a readable origin remote — the CLI identifies the AgentTeams repository from it. Without one the hook still fires but exits 1 with Could not identify the repository from the herdr event.... The herdr workspace root itself does not have to be a git repository; a non-git parent holding several repositories works, because the check applies to the target repository.

• Keep the AgentTeams CLI on the PATH of the herdr server process. A CLI that is only visible to your interactive shell is not found by hooks.

• @agentteams/cli 0.1.105 or newer — the release that added --from-herdr-event. Check with:

  agentteams worktree notify-created --help

  If --from-herdr-event is not listed, the hooks still fire but exit 1 with error: unknown option '--from-herdr-event'. Worktree creation and removal still complete — only the notification is lost. Upgrade with npm install -g @agentteams/cli@latest and check again.

Install

herdr plugin install AgentTeamsRun/herdr

herdr prints a preview (plugin id, version, commit, event list) and asks for confirmation before installing. A non-interactive shell cannot answer that prompt, so pass --yes there; without it the command exits with remote plugin install requires --yes when stdin is not interactive.

herdr plugin install AgentTeamsRun/herdr --yes

The install prints manifest does not declare platforms; platform support unknown. That warning appears because the manifest omits the optional platforms field; it does not mean the install failed or that your platform is unsupported.

Verify

herdr plugin list
herdr plugin log list --plugin agentteams

A remote install records kind: github plus owner, repo, and resolved_commit under source in plugin list. plugin log list shows the exit code and stdout/stderr of every hook run — start there when notifications do not arrive.

Update

herdr 0.8.0 has no plugin update command (it is absent from herdr plugin --help). An installed plugin is pinned to the resolved_commit captured at install time, so it does not follow later changes in the public repository on its own — but re-running the install command replaces the existing installation. There is no need to uninstall first.

herdr plugin install AgentTeamsRun/herdr

On a reinstall the preview gains a replaces: agentteams from github:AgentTeamsRun/herdr@<commit> line. herdr reuses the managed directory and rewrites the install record, so resolved_commit is resolved again.

Uninstall

herdr plugin uninstall agentteams

The owner/repo form works too: herdr plugin uninstall AgentTeamsRun/herdr.

Uninstalling removes the managed checkout but leaves the per-plugin config directory (<herdr config dir>/plugins/config/agentteams) in place. Delete it yourself if you want the plugin fully gone.

Alternative: link a manual manifest

Where GitHub is unreachable — offline or private environments — create a plugin directory, save the manifest below as herdr-plugin.toml inside it, and link it. The content matches the manifest published to the public repository.

id = "agentteams"
name = "AgentTeams worktree notifier"
version = "0.1.0"
min_herdr_version = "0.8.0"
 
[[events]]
on = "worktree.created"
command = ["agentteams", "worktree", "notify-created", "--from-herdr-event", "--quiet"]
 
[[events]]
on = "worktree.removed"
command = ["agentteams", "worktree", "notify-deleted", "--from-herdr-event", "--quiet"]

herdr plugin link <plugin-directory>

Behaviour details

Only the dotted hook event names worktree.created and worktree.removed are valid. An underscore form such as worktree_created still links, but herdr reports unknown event and the hook never fires.

--from-herdr-event reads the worktree path, branch, and repository root from the HERDR_PLUGIN_EVENT_JSON payload herdr injects, rather than from the current directory — the hook runs with the plugin root as its working directory, not the worktree.

herdr runs the worktree.removed hook after the Git worktree has been removed. That is the opposite of Orca’s archive hook, so --after-removal is not needed here. The CLI restores the same worktree identity from the parent directory so the deleted event still matches the registry entry.

herdr’s documentation does not state a hook retry or timeout policy, so AgentTeams assumes the same best-effort behaviour as Orca. A failing hook was confirmed not to reverse the local worktree operation. If an event is lost, the next Runner Git reconciliation remains the correctness path and restores AVAILABLE or MISSING.

Work under AgentTeams governance

After bootstrap, .agentteams/convention.md is available in the worktree. Before starting work, have the agent read the file and follow it as the single source of truth for working rules. See Plans for the flow from plan approval through execution and completion reporting.