Herdmates

Claude Code agent teams, native in herdr.

Herdmates makes herdr the visible home of Anthropic's native Claude Code
agent teams. The teams own spawn, mailboxes, membership, and lifecycle —
herdmates hosts them (every teammate lands as a real, steerable herdr
pane) and observes them (a mission-control board over the documented
team files). It never re-implements native-team features; it reads the
files Claude Code already writes and drives the herdr CLI.

┌Overview──────────────────────────────────────────────┐
│team session-8508a749 — 3 agents — tasks 2/5          │
└──────────────────────────────────────────────────────┘
┌Agents────────────────────────────────────────────────┐
│> · team-lead (lead)                                  │
│  · builder-98        working                         │
│  · researcher        waiting — permission prompt     │
└──────────────────────────────────────────────────────┘
┌Tasks─────────────────────────────────────────────────┐
│#3 wire spool wake        in_progress   builder-98    │
│#4 verify liveness filter pending       (blocked by 3)│
└──────────────────────────────────────────────────────┘
┌Mailbox───────────────────────────────────────────────┐
│builder-98 → team-lead: STEP 2 READY — gate clean     │
└──────────────────────────────────────────────────────┘

(Illustrative content; the four regions are the real pane-board
layout.)

The flow

1. Open herdr, type claude (via the wrapper below) — your pane becomes
   the team lead, running under the teammux shim.
2. Ask Claude to spawn teammates — each one opens as a real herdr
   pane next to you, not a hidden background process.
3. Open the board — live per-agent state with honest waiting-reason
   badges, the native task list, and the mailbox tail.
4. From the board: jump to any teammate's pane, or send a
   confirmed nudge into a stuck teammate's inbox.
5. Claude Code's team hooks push events into the board and an
   append-only recorder log — no polling lag.

Install

herdr plugin install caioniehues/herdmates

The install step runs cargo install --path . --root "$HOME/.local" —
herdr resolves manifest commands via PATH only (no shell, no relative
paths), and ~/.local/bin is where herdr itself lives. A plain
cargo build is not enough.

Recommended shell wrapper — makes claude inside a herdr pane launch
as a teammux lead automatically (plain claude everywhere else,
command claude to bypass):

# ~/.zshrc
claude() {
  if [[ -n "$HERDR_PANE_ID" ]] && command -v herdmates >/dev/null 2>&1; then
    herdmates teammux-launch "$@"
  else
    command claude "$@"
  fi
}

Surfaces

Teammux shim

A fake tmux executable on PATH plus a fake TMUX environment, set up
by herdmates teammux-launch. Claude Code's split-pane teammate mode
(teammateMode: tmux) calls what it thinks is tmux; the shim translates
every verb into herdr pane CLI calls over the herdr socket. Native
teammates land as first-class herdr panes — proven live end-to-end
(spawn, blockedBy DAG, dismissal; evidence under docs/research/).

• herdmates teammux-launch [claude args...] — takeover (default):
  the current pane becomes the lead; all args pass through to claude
  (--resume works).
• herdmates teammux-launch --split [claude args...] — split a new pane
  for the lead instead.
• Herdr-only by design: the shim's output surface IS herdr panes.
  Outside herdr, Claude Code falls back to in-process teammates.

Mission-control board

• TUI pane (pane-board entrypoint, or herdmates pane-board):
  read-only team overview — overview line, per-agent rows with
  waiting-reason badges, native task list (~/.claude/tasks/), mailbox
  tail. Wakes event-driven on hook-spool growth, falls back to polling.
  • Keys: j/k select agent · g jump to its pane · n nudge
    (confirm with y/Enter, cancel with Esc) · q quit.
• Sidebar tokens: teammate state published via
  pane report-metadata — the herdr sidebar becomes a zero-rendering
  fleet board. See Sidebar setup.
• Focus pane (focus entrypoint): the human's single next action +
  decision queue from ~/.local/share/herdmates/focus.md — one thing at
  a time, fed by the same signal engine as the board so the two surfaces
  cannot disagree.

Signal engine, recorder, hooks

• Signal engine — single source of teammate-state truth. Four
  waiting-reason classes with strict precedence (permission-prompt >
  blocked > stalled > turn-complete), two-tier stalled detection on
  transcript mtime. Doctrine: never display a wrong reason — degrade
  to reason-less "waiting" instead.
• Recorder — herdmates record --team <name>: append-only JSONL log
  of the engine's classified deltas (baselines, transitions, task
  deltas, hook signals) at ${XDG_STATE_HOME:-~/.local/state}/herdmates/ recorder/{team}.jsonl. Log schema = engine schema. Deltas-only, so
  growth is bounded by state changes rather than poll ticks, but an
  unattended long-running record still grows the file forever by
  default — pass --max-log-bytes N to rotate it once to
  {team}.jsonl.1 (overwriting any previous .1) whenever it reaches
  N bytes; omit it (or pass 0) for the previous unlimited behavior.
• Hook companion — herdmates hook <event> registered for Claude
  Code's three team hook events (TeammateIdle / TaskCreated /
  TaskCompleted) spools events per team; board and recorder consume
  the spool. Exit-2 gating capability exists but ships default-off
  and has no blocking predicate in v1.

Sidebar setup

The plugin's event hooks already publish two tokens per team lead under
source id herdmates-board ($task, $status). Rendering is your own
~/.config/herdr/config.toml: merge
docs/sidebar-rows.toml's
[ui.sidebar.agents] table in, then herdr server reload-config.

Hard-won facts (verified live against herdr 0.7.4):

• Invalid token names fail silently — reload-config reports
  "partial" and keeps the old layout. If an edit "does nothing," run
  herdr config check and re-verify every name (state_text, not
  state_label).
• Keep values telegraphic — ~20 visible columns at default sidebar
  width; herdmates enforces an 80-char wire cap but truncation is not a
  layout strategy.
• Absent tokens omit the row (safe to always configure), and
  agent-less panes never appear in the sidebar at all.

Doctrine (why it behaves the way it does)

• Honesty first: never a wrong reason, never a predicted ETA, no
  silent coverage caps. Ambiguity degrades to an explicit error (e.g.
  team resolution lists candidates rather than guessing).
• Native teams are the substrate: spawn/messaging/lifecycle belong
  to Claude Code; herdmates only reads documented team files and drives
  the herdr CLI (HERDR_BIN_PATH is the entire plugin API).
• Evidence hierarchy: live behavior > source > docs (ADR-0010).
• Writes are human-confirmed: the only team-file write is the
  confirmed nudge, under an OS advisory lock with
  read-modify-atomic-rename.

Documentation map

Development

cargo fmt && cargo clippy --all-targets -- -D warnings && cargo test
cargo install --path . --root "$HOME/.local"   # user-seat binaries
herdr plugin link .                            # refresh manifest cache

• Pure logic (file-contract parsing, token formatting, verb mapping)
  stays separate from process-spawning code — testable without a live
  herdr.
• Herdr caches the manifest at link time — relink after any
  herdr-plugin.toml change.
• Pushes to main are releases: gated, version-bumped, tagged.

Legacy: v1.x team orchestration (frozen)

The original plugin spawned heterogeneous coding-agent teams (Claude +
Codex) under a coordinating "god" session with push-based status
reporting. Frozen at v1.1.0 (ADR-0012); the code remains in-tree, the
spec at docs/legacy/spec-v1.md, and it
receives no further investment.

License

MIT