convez.ai
AgenteIntegração & APIsAvançado
david-lutz

herdr-claude-Teams

david-lutz/herdr-claude-teams

Execute agent-teams do Claude Code nativamente no herdr

Ver no GitHub
InicialPluginScore · de 0 a 100

Agent 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-teams

1 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

Estrelas
3
Forks
1
Acompanhando
0
Saúde
42%
Último commit
há 5 meses
Versão
—
Issues abertas
13
Contribuidores
1

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 uv to 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-pane maps to pane.read (visible / recent); exact scrollback-range fidelity is provisional.
  • select-pane is 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-keys into 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 stable terminal_id (resolved to the current positional pane_id per call), so sequential kill-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.

Ver o original no GitHub

Bom para

Relacionados