From herdr
Use when herding a fleet of coding agents in herdr — deciding whether to run several agents in parallel vs a single agent, setting up an agent council/team, having one agent coordinate or manage others, routing input to a specific agent by name or pane, dividing work so agents don't collide, making agent B wait on agent A, spawning helper agents without stealing focus, or running a fleet on a remote box. Holds the durable judgment of multi-agent assignment; defers all raw command syntax to the vendored herdr skill and the live CLI. Triggers: 'run several agents in parallel in herdr', 'set up an agent council/team', 'have one agent coordinate others', 'herd agents on a remote box', 'split a task across multiple coding agents', 'route this to a specific agent', 'make one agent wait for another'.
How this skill is triggered — by the user, by Claude, or both
Slash command
/herdr:herdr-multi-agentThis skill is limited to the following tools:
The summary Claude sees in its skill listing — used to decide when to auto-load this skill
You decide **how to spread work across a fleet of agents in herdr** and **how to keep them
You decide how to spread work across a fleet of agents in herdr and how to keep them coordinated without colliding. This skill is pure judgment: when to fan out, which team shape to use, how to route and sequence agents, and where fleets go wrong.
This skill holds strategy. For exact command syntax, defer to:
herdr agent skill (skills/herdr-agent-skill/SKILL.md) — it owns every raw
workspace/tab/pane create/split/read/run/send command, the HERDR_ENV=1 guard, id formats,
the spawn-an-agent recipe (split + run claude + wait for >), and wait output / wait agent-status. Do not restate these here.herdr --help and herdr agent --help for the higher-level agent commands
(start / attach / list / explain / send-by-name). Confirm their exact spelling live; this
skill never hardcodes them.https://herdr.dev/docs/agents/, /docs/integrations/, /docs/socket-api/ when
you need the agent model, the supported-agent matrix, or socket method names. Treat method names
and per-agent flags as stale-prone — confirm live.Reach for it the moment the work involves more than one agent at once: parallelizing a task,
standing up a review chain, putting a manager agent over workers, or routing a follow-up to one
specific agent in a busy fleet. If you're structuring a single agent's workspace, that's
herdr-workspace-management. If you're reading or triaging who needs attention, that's
herdr-agent-monitoring.
herdr lets you reach an agent by pane id (1-3) or by agent name. The choice is strategic:
1-3 may be a different pane later.
For one-shot, in-the-moment coordination, pane ids are fine (re-read them from pane list first).agent list,
can be read or sent input by agent name, can be waited on by agent state, and can be directly
attached." For a long-lived fleet — councils, manager/worker, anything you'll route to repeatedly
— name your agents and address them by name. You stop chasing renumbered pane ids.Confirm the exact herdr agent ... syntax live (herdr agent --help). The capability above is
durable; the spelling is not.
The discriminator is collision risk, not task size.
| Situation | Do this |
|---|---|
| Subtasks are independent and touch disjoint files/dirs | Fan out — one agent per subtask |
| Work is coupled, or agents would edit the same files | One agent — serialize it |
| Same repo, parallel agents | One workspace (and ideally one git worktree) per agent so edits can't clobber each other |
| You want higher confidence on one hard decision | Council — several agents, same problem, then reconcile |
| Output of step N feeds step N+1 | Pipeline — gate each stage on the prior agent's status |
| Many similar subtasks + a coordinator | Manager/worker — one agent fans out and collects |
Rule of thumb: if you can't name the disjoint slice each agent owns, you're not ready to fan
out. Define ownership (by directory, by file glob, by worktree) before spawning. Collision
avoidance is the whole game — see references/fan-out-patterns.md.
Pick by the relationship between the agents, not their count.
references/councils-and-teams.md.references/councils-and-teams.md.references/councils-and-teams.md.herdr detects a public agent_status: idle, working, blocked, done, unknown. Coordinate
on these semantics rather than scraping the screen:
done before B consumes A's output. (Use the vendored
wait agent-status recipe; don't restate it.)done means finished but not yet reviewed by you. It does not mean "correct." Always
read the pane after done before feeding its output downstream — a done worker can be done and
wrong.blocked means the agent needs input — a permission prompt or a question. In a fleet, a
blocked agent is your cue to route input to it by name and unblock it, not to wait longer.unknown usually means screen detection has nothing to go on — relevant because agents that
report lifecycle/session identity natively (e.g. Claude Code, Codex, Droid, OpenCode, Copilot,
Cursor) give you more reliable working/blocked/done signals than agents herdr classifies
purely from the screen. Prefer native-reporting agents for the legs of a pipeline you gate on.
Confirm the current support matrix via /docs/integrations/; treat it as live.When detection looks wrong (a worker stuck at unknown, a false blocked), use the agent
explain command to see how the state was decided. Confirm its exact spelling live.
Alert the human at milestones. A fleet that runs for a while shouldn't require the user to
babysit it. When the whole fan-out finishes, or the first agent goes blocked and needs a
decision, fire a desktop toast: herdr notification show "<title>" [--body TEXT] [--sound none|done|request] [--position …] (verified herdr 0.6.10 — confirm flags live). Pair it
with the wait you already use, e.g. wait for the last worker to reach done, then
herdr notification show "fleet done" --sound done. Keep it to genuine attention points (all-done,
first-blocked), not per-step chatter.
When a manager agent spawns workers, or you add a helper mid-task, use --no-focus on the
split/create so you don't yank the user's terminal around. The vendored skill's "spawn a new agent
and give it a task" recipe is the canonical sequence — reference it, don't duplicate it. The
strategy layer here: spawn into the right container (a fresh workspace/worktree per parallel
worker; a sibling pane only for tightly-coupled helpers).
Running a fleet on a remote box is the highest-leverage herdr use case: the server lives on the
box, so the fleet survives SSH drops and your laptop sleeping. Three durable cautions before you
scale up there: herdr does not sandbox agents (egress/IAM is your problem), it's early
software (keep a fallback path), and one-worktree-per-agent matters even more remotely where you
can't eyeball collisions. Full remote recipe and gotchas: references/remote-fleets.md.
workspace/tab/pane create/split/read/run/send + wait output / wait agent-status +
the spawn-an-agent and coordinate recipes → vendored herdr skill
(skills/herdr-agent-skill/SKILL.md). This skill calls those; it does not respell them.--resume/--session
flags → herdr-workspace-management.herdr-layouts.herdr-agent-monitoring.config.toml, keybindings, detection rules → herdr-configuration.npx claudepluginhub jbaham2/herdr-plugin --plugin herdrGuides creation, editing, and verification of skills for AI coding agents using test-driven development with subagent scenarios. Use when authoring or debugging skills.