herdr-claude-Teams
david-lutz/herdr-claude-teams
Execute agent-teams do Claude Code nativamente no herdr
Ver no GitHubAgent para rodar Claude Code agent-teams dentro do herdr, traduzindo comandos tmux para chamadas de socket API. Permite que teammates apareçam como splits nativos do herdr em vez de panes tmux, mantendo metadados e estado dos agentes.
Instalação
npx convez-ai david-lutz/herdr-claude-teams1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Executar equipes de agentes Claude dentro do herdr interativamente
- Integrar Claude Code com o terminal multiplexado herdr
- Coordenar múltiplos agentes de IA em uma interface unificada
Veredito

Ferramenta especializada e bem engenheirada para integrar agent-teams do Claude Code com herdr, resolvendo um problema específico de fluxo de trabalho. Requer macOS, herdr rodando e Claude Code — não é uma solução genérica, mas extremamente prática para quem usa esse ecossistema.
README
A tradução para o português deste README ainda está na fila.
herdr-claude-teams
Run Claude Code's experimental agent-teams feature inside herdr — teammates spawn as native herdr panes instead of tmux panes, with herdr's sidebar metadata, agent-state, and notifications.
It works by putting a tiny tmux shim on PATH: Claude's agent-teams drives
teammates by shelling out to tmux, and the shim translates those tmux commands
into herdr socket-API calls. No real tmux is involved.
Requirements
- macOS with herdr running (validated against herdr 0.6.10)
- Claude Code (validated against 2.1.174)
- Python ≥ 3.11 and
uvto install
Install
uv tool install . # from a clone of this repo
# or: uv tool install git+https://github.com/david-lutz/herdr-claude-teams
This puts herdr-claude-teams on your PATH.
Usage
Inside a herdr pane, run herdr-claude-teams in place of claude — all arguments
pass through:
herdr-claude-teams # like `claude`
herdr-claude-teams --resume # args are forwarded unchanged
The launcher detects the herdr pane (via HERDR_ENV / HERDR_SOCKET_PATH /
HERDR_PANE_ID), fakes a tmux environment, enables agent-teams, installs the
shim, and execs claude. When Claude spawns a teammate it appears as a herdr
split. (Agent-teams is interactive-only; this has no effect in claude -p
headless mode, which uses in-process teammates.)
How it works
herdr pane (you run herdr-claude-teams)
└─ exports TMUX/TMUX_PANE from HERDR_*, CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1,
prepends a shim dir to PATH, execs claude
claude → `tmux split-window …`, `send-keys …`, `capture-pane …`
→ shim `tmux` → JSON-RPC → herdr socket (pane.split / send_text / read …)
The teammate's own environment is delivered by Claude as an env K=V… prefix on
the command it types into the new pane; the shim additionally injects
TMUX_PANE (which real tmux would supply but herdr does not).
Limitations
- Interactive only — the tmux teammate backend is gated to the herdr TUI; it
is not exercised by
claude -p. - One level of teammates (MVP). Deeply nested teams are untested.
capture-panemaps topane.read(visible / recent); exact scrollback-range fidelity is provisional.select-paneis best-effort (focuses the pane's tab — herdr has no absolute pane focus).- Teammate panes don't self-close on agent exit. Teammates are launched by
send-keysinto the pane's shell (not as the pane's exec target), so a pane only closes when Claude explicitly tears it down — if the agent process exits on its own, the pane falls back to a live shell prompt. Explicit teardown is reliable: the shim's Claude-facing pane id is herdr's stableterminal_id(resolved to the current positionalpane_idper call), so sequentialkill-panes close every pane even as herdr renumbers survivors. - macOS + herdr only.
Uninstall / rollback
uv tool uninstall herdr-claude-teams
rm -rf "${XDG_CACHE_HOME:-$HOME/.cache}/herdr-claude-teams" # the generated shim dir
herdr-claude-teams writes nothing to your shell rc, herdr config, or ~/.claude, so
there is no other state to undo.
Development
uv sync # create the environment
./test # run the whole suite (uv run pytest)
HERDR_CLAUDE_TEAMS_LIVE=1 ./test tests/test_live_smoke.py # opt-in live smoke vs a real herdr
HERDR_CLAUDE_TEAMS_DEBUG=/tmp/trace.log herdr-claude-teams # JSON trace of every shim call
Runtime is standard-library only (see openspec/changes/herdr-claude-teams/design.md,
decision D2a); uv manages the dev environment.