# herdr: multiplekser agentów ze skryptowalnym API

URL: https://developertoolkit.ai/pl/ecosystem/agent-tools/herdr-agent-multiplexer/
Description: Zainstaluj herdr 0.9.1, zobacz, jak naprawdę wykrywa zablokowanych agentów, i każ jednemu agentowi prowadzić trzech wykonawców i recenzenta.

herdr to otwartoźródłowy multiplekser terminala dla agentów kodujących. Trzyma agentów w prawdziwych panelach terminala na serwerze w tle, oznacza panele jako `working`, `blocked` albo `idle` i udostępnia CLI oraz socket API, którymi jeden agent uruchamia pozostałych, wysyła im polecenia, czeka na nich, czyta ich wyjście. Dla Claude Code, Codeksa i Cursora stan daje detekcja ekranu, nie hooki.

Masz pięciu agentów w ruchu. Jeden jest w połowie refaktoru, drugi skończył jedenaście minut temu, trzeci od twojego wyjścia po kawę czeka na zgodę na uprawnienia, a co robią dwaj ostatni, odtworzysz tylko ze scrollbacku. W zwykłym tmuksie dowiadujesz się tego, odwiedzając każdy panel, a zablokowany agent zdążył już zmarnować swoje jedenaście minut.

Ta strona jest dla programistów, którzy prowadzą kilku agentów terminalowych naraz, i dla tech leadów, którzy decydują, czy zespół ma ustandaryzować się na skryptowalnym terminalu do floty agentów. Opisuje herdr 0.9.1 (wydany 2026-09-16), aktualne wydanie na dzień 2026-09-26.

## Co znajdziesz na tej stronie

- Działającą instalację z integracjami dla poszczególnych agentów i skillem herdr
- Rzetelny model tego, kiedy stan `blocked` jest wiarygodny i jak go debugować, kiedy nie jest
- Przepływ z recenzentem: jedną sekwencję poleceń, która uruchamia recenzenta Codex obok twojej sesji i czyta jego werdykt
- Skrypt rozdzielający pracę na trzech wykonawców w worktree herdr i jednego recenzenta, z niezależnym uruchomieniem testów jako bramką
- Dwa prompty do skopiowania, dzięki którym agent-orkiestrator sam steruje herdr
- Pułapki: placeholder w npm, pomyłkę z Herd i granice detekcji stanu

## Kiedy herdr jest właściwym narzędziem?

herdr się opłaca, gdy prowadzisz co najmniej trzech agentów terminalowych, chcesz widzieć, który cię potrzebuje, bez odwiedzania paneli, i chcesz, żeby flotą sterował agent, a nie tylko ty. Słabo pasuje, gdy zespół chce graficznej tablicy z diffami i review.

| Potrzebujesz | Użyj | Dlaczego |
| --- | --- | --- |
| Jednej lub dwóch sesji Claude Code | Wbudowane w Claude Code `--worktree` i agent view | Bez nowego pliku binarnego; zobacz [równoległą pracę agentów](/pl/ecosystem/agent-tools/parallel-agents/) |
| Mieszanej floty (Claude Code, Codex, Cursor) w jednym terminalu, ze skryptami | herdr | 24 rodzaje agentów, jedno CLI dla wszystkich |
| Zera nowych zależności albo zespołu bezpieczeństwa, który nie zatwierdzi nowego pliku binarnego | tmux | Zobacz [tmux dla floty agentów](/pl/ecosystem/agent-tools/tmux-for-agent-fleets/) |
| Aplikacji desktopowej z diffem i review dla każdego zadania | Conductor, Orca i podobne | Zobacz [alternatywne IDE i powłoki agentów](/pl/ecosystem/agent-tools/agent-shells/) |

**Popularność na dzień 2026-09-26:** repozytorium `herdrdev/herdr` miało 40 779 gwiazdek na GitHubie, odczytanych przez GitHub API na potrzeby dossier narzędzi agentowych tego serwisu. Repozytorium powstało 2026-03-27 i ma licencję Apache-2.0. Gwiazdki mierzą uwagę, nie przydatność.

## Zainstaluj herdr i integracje agentów

herdr to jeden plik binarny napisany w Ruście. Zainstaluj go oficjalnym skryptem albo menedżerem pakietów, a potem dodaj integrację dla każdego agenta, którego używasz.

1. Zainstaluj plik binarny (terminal, Linux lub macOS):

   ```bash
   curl -fsSL https://herdr.dev/install.sh | sh
   # albo: brew install herdr
   # albo: mise use -g herdr
   ```

   Na Windowsie uruchom `powershell -ExecutionPolicy Bypass -c "irm https://herdr.dev/install.ps1 | iex"`. Dokumentacja instalacji herdr opisuje Windows jako ogólnie dostępny, z udokumentowanymi ograniczeniami platformy.

2. Zainstaluj integrację dla każdego agenta. Każda zakładka to to samo polecenie `herdr integration install` z inną nazwą agenta:

     **Claude Code**

       ```bash
       herdr integration install claude
       ```
       Zapisuje `hooks/herdr-agent-state.sh` w `~/.claude` (albo w `CLAUDE_CONFIG_DIR`) i dodaje hook `SessionStart` do `settings.json`. Katalog musi już istnieć, więc najpierw raz uruchom `claude`.

     **Codex**

       ```bash
       herdr integration install codex
       ```
       Zapisuje `herdr-agent-state.sh` w `~/.codex` (albo w `CODEX_HOME`), aktualizuje `hooks.json` i ustawia `[features] hooks = true` w `config.toml`. Codex poprosi cię o zaufanie nowym hookom, zanim je uruchomi.

     **Cursor**

       ```bash
       herdr integration install cursor
       ```
       Dodaje tożsamość sesji dla Cursor Agent CLI. Uruchamiaj go w panelu przez `herdr agent start <nazwa> --kind cursor`, które używa kanonicznego pliku wykonywalnego herdr dla tego rodzaju, więc nie musisz znać nazwy binarki. Katalog `~/.cursor` (albo `CURSOR_CONFIG_DIR`) musi już istnieć. Przywracanie po restarcie serwera uruchamia `cursor-agent --resume`, więc trzymaj `cursor-agent` w `PATH`. Dokumentacja samego Cursora nazywa komendę CLI `agent` i nie wspomina o `cursor-agent` (sprawdzone 2026-10-12), więc zanim zaufasz przywracaniu, sprawdź, którą z tych dwóch nazw daje twoja instalacja Cursora.

   We wszystkich trzech przypadkach integracja raportuje **tożsamość sesji**, dzięki której herdr wznawia właściwą rozmowę po restarcie serwera. Nie raportuje stanu cyklu życia. Dlaczego to ważne, wyjaśnia następna sekcja.

3. Zainstaluj skill herdr, żeby agent działający w panelu herdr znał CLI. To samo polecenie działa dla Claude Code, Codeksa i Cursora:

   ```bash
   npx skills add herdrdev/herdr --skill herdr -g
   ```

   `-g` instaluje skill globalnie dla wszystkich obsługiwanych agentów na maszynie; bez niego trafia do bieżącego projektu. `herdr --skill` wypisuje kopię zgodną z zainstalowaną wersją.

4. Sprawdź konfigurację:

   ```bash
   herdr integration status
   herdr
   ```

   `herdr` otwiera TUI. Podziel panel, uruchom w nim `claude` albo `codex`, a pasek boczny pokaże agenta i jego stan. `ctrl+b q` odłącza klienta; ponowne `herdr` podłącza go z powrotem, a agenci w tym czasie pracują dalej.

**Dwie pułapki instalacji**

**Nie uruchamiaj `npm install -g herdr`.** Pakiet npm `herdr` to zarezerwowany placeholder w wersji 0.0.0, a nie to narzędzie. **herdr to nie Herd.** [herdr](https://herdr.dev/) to ten multiplekser terminala; [Herd](https://joinherd.ai/) to osobna aplikacja desktopowa. Starsze linki prowadzą do `ogulcancelik/herdr`; repozytorium to teraz `herdrdev/herdr`.

**Koszt kontekstu.** Sam herdr nie dodaje nic do kontekstu agenta. Skill dodaje: jego `SKILL.md` miał 2026-09-26 około 2100 słów (13,9 KB). Jego opis każe agentowi sięgać po niego tylko wtedy, gdy wprost wspomnisz herdr, więc ładuje się na żądanie. Uruchom `/context` w Claude Code przed zadaniem z herdr i po nim, żeby zobaczyć, ile cię to kosztuje.

## Skąd herdr wie, że agent jest zablokowany?

To funkcja, dla której wdrażasz herdr, i najczęstsze założenie na jej temat jest błędne. herdr daje każdemu panelowi dokładnie jedno **źródło stanu** (w dokumentacji: *state authority*):

| Źródło stanu | Agenci (dokumentacja herdr 0.9.1) |
| --- | --- |
| Hooki cyklu życia lub plugin, gdy integracja jest zainstalowana | Pi, OMP, Kimi Code CLI, MastraCode, OpenCode, Kilo Code CLI |
| **Manifest ekranu** (integracja daje tylko tożsamość sesji) | **Claude Code, Codex, Cursor Agent CLI**, GitHub Copilot CLI, Devin CLI, Droid, Qoder CLI, Qwen Code, Letta Code, Hermes Agent, Grok CLI, Antigravity CLI |
| Manifest ekranu, bez integracji | Amp, Kiro CLI, Maki, Muse |
| Wykrywani, słabiej przetestowani | Gemini CLI, Cline |

Manifest ekranu to zestaw reguł, które herdr sprawdza na żywym dole bufora panelu. herdr oznacza panel jako `blocked` tylko wtedy, gdy ten zrzut pasuje do **znanego** okna zgody, pytania albo uprawnień. Gdy żadna reguła nie pasuje, panel wraca do `idle`, a nie do `blocked`. Nowe okno uprawnień albo agent zadający pytanie w nieznanym układzie może więc wyglądać na `idle`, choć czeka na ciebie.

Trzy konsekwencje dla wszystkiego, co automatyzujesz:

- Czekanie na `idle` może się zakończyć, gdy agent w rzeczywistości czeka na odpowiedź. Zanim zareagujesz na `idle`, zawsze przeczytaj panel.
- Codex może spaść do `unknown` zamiast `idle`. `unknown` znaczy, że agent jest obecny, ale herdr nie umie go sklasyfikować, a nie że praca się udała.
- herdr aktualizuje manifesty detekcji z herdr.dev w tle, więc detekcja może się poprawić bez nowej wersji binarki. Ustaw `[update] manifest_check = false`, jeśli twoja polityka tego zabrania.

Gdy panel pokazuje zły stan, zapytaj herdr o powód:

```bash
herdr agent explain reviewer
herdr agent explain --file screen.txt --agent codex --json
```

Wynik podaje manifest, jego wersję, dopasowaną regułę i powód powrotu do stanu domyślnego (`default_known_agent_idle_fallback`), gdy nic nie pasowało. Tryb na żywo pyta działający serwer, więc po aktualizacji herdr zrestartuj serwer, zanim użyjesz `explain`; `--file` działa lokalnie bez tego. Dołącz wynik z `--json` do zgłoszenia błędu w `herdrdev/herdr`.

## Uruchom recenzenta obok swojej sesji

Najmniejsza użyteczna automatyzacja: z panelu, w którym pracujesz, uruchamiasz w nowym podziale agenta Codex o nazwie `reviewer`, dajesz mu diff do przejrzenia i czytasz, co odpowie. Uruchom to w panelu terminala wewnątrz herdr:

```bash
split=$(herdr pane split --current --direction right --no-focus)
review_pane=$(printf '%s\n' "$split" | jq -r '.result.pane.pane_id')
herdr agent start reviewer --kind codex --pane "$review_pane"
herdr agent prompt reviewer "Review the current diff for missed error paths and missing tests. List findings as file:line - problem - fix." --wait --timeout 300000
herdr agent read reviewer --source recent-unwrapped --lines 120
```

Co zobaczysz: po prawej otwiera się panel z Codeksem. `agent start` wraca, gdy herdr wykryje Codeksa i oznaczy go jako gotowego. `agent prompt --wait` wraca, gdy recenzent ustabilizuje się w `idle`, `done` albo `blocked`, a `agent read` wypisuje ostatnie 120 wyrenderowanych wierszy bez zawijania, więc długie ścieżki zostają w jednej linii. Polecenia tworzące wypisują JSON, dlatego ID panelu wyciągasz przez `jq` zamiast go zgadywać.

Codex startuje na swoim domyślnym modelu, na dzień 2026-10-12 jest to GPT-6.1 Sol (zobacz [przegląd modeli](/pl/ecosystem/models/)). Argumenty po `--` trafiają do agenta bez zmian, więc `-- -m <model>` przypina inny.

Jeśli recenzent zatrzyma się na oknie zgody, poczekaj na to i odpowiedz świadomie:

```bash
herdr agent wait reviewer --until blocked --timeout 120000
herdr agent read reviewer --source recent-unwrapped --lines 80
herdr agent send-keys reviewer esc
```

**Prompt do skopiowania: niech agent sam uruchomi recenzenta**

```text
We are inside herdr (check that HERDR_ENV=1; stop and tell me if it is not).
Use the herdr skill. Split the current pane to the right without taking focus,
start a Codex agent named reviewer in the new pane, and prompt it with:
"Review the diff between main and the current branch. Report only real defects:
file:line, the failing scenario, and the fix. Do not edit files."
Wait with --wait and a 300000 ms timeout. If it returns blocked, read the pane
and show me the prompt instead of answering it. Otherwise read the last 120
unwrapped lines and summarise the findings as a checklist, most severe first.
```

## Rozdziel pracę na trzech wykonawców i jednego recenzenta

To przepływ, który uzasadnia herdr: orkiestrator daje trzy niezależne zadania trzem wykonawcom, każdemu we własnym worktree, sam weryfikuje każdy wynik, uruchamiając testy, i przekazuje każdą zieloną gałąź jednemu recenzentowi. Wkraczasz tylko wtedy, gdy agent jest `blocked` albo bramka nie przejdzie.

herdr 0.9.1 umie sam tworzyć worktree: `herdr worktree create` zakłada worktree Gita, otwiera go jako workspace zgrupowany pod repozytorium i zwraca nowy panel główny. Izolacja powinna mieć jednego właściciela. Worktree tworzy albo herdr (jak niżej), albo agent własną flagą (`claude --worktree <nazwa>`, `codex --worktree`), nigdy oba naraz.

```bash
#!/usr/bin/env bash
# bin/herdr-fanout - run from a herdr pane at the repository root
set -euo pipefail
[ "${HERDR_ENV:-}" = 1 ] || { echo "run this inside a herdr pane" >&2; exit 1; }

TASKS=(rate-limit webhook-idempotency cache-invalidation)
SETUP_CMD="npm ci"   # a new worktree has no node_modules and no gitignored .env
TEST_CMD="npm test"
REPO=$(git rev-parse --show-toplevel)
declare -A PANE WT
STARTED=()   # only tasks whose agent started get supervised

# 1. One worktree and one implementer per task. Agent names must match
#    [a-z][a-z0-9_-]{0,31}; the "impl-" prefix keeps them valid and unique.
for task in "${TASKS[@]}"; do
  name="impl-$task"
  WT[$task]="$REPO-worktrees/$task"   # explicit path, reused by the gate below
  created=$(herdr worktree create --cwd "$REPO" --branch "agent/$task" --path "${WT[$task]}" --no-focus)
  PANE[$task]=$(printf '%s\n' "$created" | jq -r '.result.root_pane.pane_id')
  herdr pane run "${PANE[$task]}" "$SETUP_CMD; echo SETUP_EXIT=\$?"
  setup=$(herdr pane wait-output "${PANE[$task]}" --regex 'SETUP_EXIT=[0-9]+' --timeout 600000 \
    | jq -r '.result.matched_line') || setup="SETUP_EXIT=timeout"
  [ "$setup" = "SETUP_EXIT=0" ] || { echo "!! $task: setup failed ($setup)"; continue; }
  herdr agent start "$name" --kind claude --pane "${PANE[$task]}" --timeout 60000 || {
    echo "!! $task: agent not ready"
    herdr agent read "$name" --source recent-unwrapped --lines 40 || true
    continue
  }
  herdr agent prompt "$name" "Task: $task (see docs/tasks/$task.md for the acceptance criteria).
Stay inside this worktree. Write the failing test first, make it pass, run $TEST_CMD,
then commit on this branch and stop. Do not touch code outside this task."
  # A prompt without --wait only acknowledges the keystrokes. Confirm the turn began,
  # or step 3 could see the old "idle" and gate unchanged code.
  herdr agent wait "$name" --until working --until blocked --timeout 30000 >/dev/null || {
    echo "!! $task: prompt not picked up"
    herdr agent read "$name" --source recent-unwrapped --lines 40 || true
    continue
  }
  STARTED+=("$task")
done

# 2. A reviewer in a split of the primary checkout.
split=$(herdr pane split --current --direction down --no-focus)
herdr agent start reviewer --kind codex --pane "$(printf '%s\n' "$split" | jq -r '.result.pane.pane_id')"

# 3. Supervise: park until each implementer settles, then gate and review.
for task in "${STARTED[@]}"; do
  name="impl-$task"
  status=$(herdr agent wait "$name" --until done --until idle --until blocked \
    --timeout 1800000 | jq -r '.result.agent.agent_status') || status=timeout
  if [ "$status" != done ] && [ "$status" != idle ]; then
    echo "!! $task: $status - needs a human"
    herdr agent read "$name" --source recent-unwrapped --lines 40 || true
    continue
  fi
  # Independent gate: run the tests in a fresh pane of the same worktree.
  gate=$(herdr pane split "${PANE[$task]}" --direction down --cwd "${WT[$task]}" --no-focus \
    | jq -r '.result.pane.pane_id')
  herdr pane run "$gate" "$TEST_CMD; echo GATE_EXIT=\$?"
  result=$(herdr pane wait-output "$gate" --regex 'GATE_EXIT=[0-9]+' --timeout 900000 \
    | jq -r '.result.matched_line') || result="GATE_EXIT=timeout"
  echo "== $task: $result"
  [ "$result" = "GATE_EXIT=0" ] || continue
  herdr agent prompt reviewer "Review branch agent/$task against main: git diff main...agent/$task.
Report only defects as file:line - failing scenario - fix. Do not edit files." \
    --wait --timeout 600000 || { echo "!! $task: reviewer did not settle - read the reviewer pane"; continue; }
  herdr agent read reviewer --source recent-unwrapped --lines 80 || true
done
```

Projekt opiera się na czterech szczegółach:

- **Najpierw przygotowanie, potem start.** Każdy worktree najpierw uruchamia `SETUP_CMD`, a nieudana instalacja albo `agent start`, który nie jest gotowy, pomija to zadanie zamiast zatrzymywać skrypt.
- **Najpierw prompt dla wszystkich, potem czekanie.** Krok 1 wysyła prompty bez `--wait`, więc trzej wykonawcy pracują jednocześnie. Prompt bez `--wait` potwierdza tylko, że herdr wpisał tekst, a samodzielne `agent wait` wraca od razu, jeśli stan już pasuje. Dlatego krok 1 czeka `--until working`, zanim pójdzie dalej. Inaczej krok 3 mógłby odczytać `idle` sprzed promptu i puścić bramkę na niezmienionym kodzie. Krok 3 czeka potem na wykonawców po kolei, co nic nie kosztuje, bo i tak pracują równolegle.
- **Orkiestrator nie wierzy wykonawcy na słowo, że „testy przechodzą”.** Bramka uruchamia `TEST_CMD` w osobnym panelu i czyta kod wyjścia z wyjścia panelu przez `pane wait-output`, polecenie, które nic nie wie o agentach. Podział panelu dostaje `--cwd` ze ścieżką worktree, bo bez tego nowy panel podąża za konfigurowalną polityką `terminal.new_cwd` i mógłby uruchomić testy gdzie indziej.
- **`--timeout` wszędzie i `||` po każdym czekaniu.** Bez limitu `agent wait` i `pane wait-output` czekają w nieskończoność. Po przekroczeniu czasu, a także przy błędach takich jak `agent_prompt_stalled` czy `agent_blocked`, herdr wypisuje JSON na stderr i kończy się kodem 1, który `set -e` zamieniłby w przerwany przebieg. Dlatego każde czekanie, każde `agent start` i prompt dla recenzenta mają gałąź `||`, która zapisuje zadanie w logu i idzie dalej, a diagnostyczne wywołania `agent read` kończą się `|| true`. Jedyny wyjątek jest celowy: jeśli recenzent nie wystartuje w kroku 2, skrypt zatrzymuje się, zanim cokolwiek przejdzie przez bramkę.

**Prompt do skopiowania: Claude Code jako orkiestrator**

```text
You are the orchestrator for this repository and you are running inside herdr
(verify HERDR_ENV=1 first). Use the herdr skill and run `herdr api schema` if you
are unsure of a command; do not guess flags.

1. For each of these tasks: rate-limit, webhook-idempotency, cache-invalidation,
   run `herdr worktree create --cwd . --branch agent/<task> --no-focus`, take
   .result.root_pane.pane_id, and start a Claude Code agent named impl-<task> there.
2. Prompt each implementer without --wait: write the failing test from
   docs/tasks/<task>.md first, make it pass, run npm test, commit, stop.
3. Start a Codex agent named reviewer in a split of this pane.
4. Park on each implementer with
   `herdr agent wait impl-<task> --until done --until idle --until blocked --timeout 1800000`.
   If it returns blocked, read 40 unwrapped lines and ask me; never answer a
   permission prompt yourself.
5. For each finished task, run npm test yourself in a new split of that
   worktree and check the exit code. Only passing branches go to the reviewer.
6. End with a table: task, gate exit code, reviewer findings (count and worst),
   and whether the branch is ready for a pull request.
```

## Jak zweryfikować pracę floty bez czytania każdego diffu?

Powyższy skrypt już rozdziela trzy kontrole, które się liczą. Zapisz je wprost, zanim zwiększysz flotę powyżej trzech wykonawców:

| Bramka | Co ją dowodzi | Kto za nią odpowiada |
| --- | --- | --- |
| Zachowanie | Kryteria akceptacji spisane przed uruchomieniem i zamienione w nieprzechodzący test, który wykonawca musi naprawić | Autor zadania; zobacz [kryteria akceptacji](/pl/workflows/plan/acceptance-criteria/) |
| Testy i build | `TEST_CMD` uruchomione przez orkiestratora we własnym panelu, ze sprawdzonym kodem wyjścia, a potem ten sam zestaw w CI | Lokalnie orkiestrator, CI jako źródło prawdy |
| Review | Agent-recenzent od innego dostawcy niż wykonawca (tu Codex przegląda Claude Code), uwagi jako plik, linia i scenariusz | Agent-recenzent, a potem człowiek, który czyta uwagi zamiast całego diffu |
| Merge | Pull request z dowodami: przebiegiem testów, uwagami recenzenta i opisem zmian | Zatwierdza człowiek; zobacz [pakiet dowodów](/pl/workflows/ship/evidence-bundle/) |

Rola herdr jest wąska i użyteczna: rzetelnie mówi, kiedy każda bramka może ruszyć, a `agent read` daje transkrypt do dołączenia. Nigdy nie dowodzi, że kod jest poprawny. To zadanie testów, recenzenta i CI. Etap review szczegółowo opisuje strona o [review pull requestów agentów](/pl/workflows/ship/agent-pr-review/).

## Uruchamiaj agentów na innej maszynie albo w sandboksie w chmurze

herdr trzyma panele przy życiu na serwerze w tle, więc zamknięta klapa laptopa czy zerwane połączenie SSH niczego nie zatrzymują. Dwie funkcje rozszerzają to na inne maszyny:

- **Zapisane maszyny SSH.** Dodaj maszynę raz przez `herdr machine add workbox --label "Build machine"`. Potem poprzedź dowolne polecenie API flagą `--machine`, żeby wykonać je tam, bez otwartego okna herdr:

  ```bash
  herdr --machine "Build machine" agent list
  herdr --machine "Build machine" agent prompt w1:p1 "review this change"
  ```

  Etykieta musi dokładnie pasować do zapisanej maszyny (wielkość liter ma znaczenie). ID i nazwy agentów należą do jednego serwera, więc wybranie maszyny w TUI nie przekierowuje poleceń CLI działających w istniejącym panelu. Zaktualizuj herdr na obu maszynach; nieudane polecenie zdalne nigdy nie wykonuje się lokalnie zamiast tego.

- **Sandboksy E2B.** E2B publikuje plugin do herdr, który wysyła bieżący checkout, razem z niezacommitowanymi zmianami, do świeżego sandboksa E2B w chmurze. Potrafi też puścić kilku agentów na to samo zadanie i ocenić ich jednym wspólnym sprawdzianem:

  ```bash
  herdr plugin install e2b-dev/herdr-e2b-sandbox
  ```

  Wymaga herdr 0.7.0 lub nowszego, Node.js 22 lub nowszego, `jq`, CLI `e2b` i klucza API E2B. W interaktywnym terminalu `herdr plugin install` pokazuje przed instalacją podgląd do zatwierdzenia (`--yes` go pomija); przeczytaj go, bo plugin obsługuje dane logowania twoich agentów. Porównanie E2B z innymi formami izolacji znajdziesz na stronie o [sandboksach dla agentów](/pl/ecosystem/agent-tools/sandboxes/).

Po restarcie serwera albo maszyny herdr odtwarza zapisany układ i może wznowić obsługiwane sesje agentów przez ich integracje. Oryginalne procesy restartu nie przeżywają. Dostęp do tej samej floty z telefonu opisuje strona o [klientach zdalnych i mobilnych](/pl/ecosystem/agent-tools/remote-mobile/).

## Skryptuj herdr przez socket API

CLI jest klientem lokalnego socket API: JSON rozdzielany znakami nowej linii przez gniazdo Unix domain socket (na Windowsie przez named pipe), jedno żądanie na linię, odpowiedzi dopasowane po `id`. Domyślne gniazdo to `~/.config/herdr/herdr.sock`; nazwane sesje mają własne. Po surowe API sięgaj tylko wtedy, gdy potrzebujesz długotrwałego strumienia zdarzeń, na przykład żeby reagować na każdego agenta w stanie `blocked` zamiast odpytywać:

```json
{"id":"sub_1","method":"events.subscribe","params":{"subscriptions":[{"type":"pane.agent_status_changed","pane_id":"w1:p1","agent_status":"blocked"}]}}
```

Generuj kontrakt z zainstalowanej binarki, zamiast kopiować nazwy metod z artykułów, także z tego:

```bash
herdr api schema --json > herdr-api.schema.json
```

Klienci powinni ignorować nieznane pola i traktować nieobsługiwaną metodę jak zwykły błąd, bo serwer sam ogłasza, co obsługuje.

**Pułapki herdr, sprawdzone na herdr 0.9.1**

- **„herdr używa hooków cyklu życia dla Claude Code, Codeksa i Cursora”.** Nie używa. Dla tych trzech stan ustala manifest ekranu, a integracje raportują tożsamość sesji do wznawiania.
- **„Nierozpoznane okno pokazuje się jako `working`”.** Pokazuje się jako `idle`. Zanim zareagujesz na `idle`, przeczytaj panel.
- **`npm install -g herdr`.** Placeholder w wersji 0.0.0. Użyj skryptu instalacyjnego, Homebrew albo mise.
- **herdr i Herd.** Różne produkty, jedna litera różnicy.
- **Przypięte wycofane modele w starych przykładach.** Dokumentacja automatyzacji herdr wciąż przekazuje Codeksowi `-- -m gpt-5.4`. GPT-5.4 wycofano z Codeksa 2026-08-31; usuń przypięcie albo użyj aktualnego modelu z [przeglądu modeli](/pl/ecosystem/models/).

## Co się psuje, gdy prowadzisz flotę w herdr?

**`agent start` kończy się błędem `agent_pane_busy`.** Docelowy panel nie stoi na bezczynnym prompcie powłoki: pierwszy plan zajmuje polecenie, edytor albo agent. Uruchamiaj agentów tylko w panelach, które właśnie utworzyłeś, albo zatrzymaj to, co tam działa (`herdr agent send-keys <nazwa> ctrl+c` lub `herdr pane send-keys <panel> ctrl+c`), i spróbuj ponownie. `agent start` nigdy nie tworzy układu za ciebie.

**`agent start` zwraca `agent_not_ready`.** Agent otworzył się w nowym worktree na ekranie zaufania albo zgody, a detekcja zgłosiła `blocked` podczas startu. Przeczytaj panel, odpowiedz przez `agent send-keys`, a potem wyślij prompt. Skrypt powyżej traktuje to jako pominięte zadanie, zamiast przerywać cały przebieg przez `set -e`.

**`agent start` kończy się błędem `invalid_agent_name` albo `agent_name_taken`.** Nazwy muszą pasować do `[a-z][a-z0-9_-]{0,31}` i być unikalne wśród żywych agentów. Wyprowadź nazwę raz ze sluga zadania, jak robi to `impl-$task`, i adresuj nią każde kolejne polecenie. Jeśli slug może zawierać wielkie litery, kropki albo ukośniki, znormalizuj go przed uruchomieniem agenta, a nie po.

**Orkiestrator czeka w nieskończoność.** Czekanie bez `--timeout` nie ma domyślnego limitu. Dodaj limit do każdego `agent wait`, `agent prompt --wait` i `pane wait-output`, a kod wyjścia 1 traktuj jako „idź i sprawdź”.

**Prompt poszedł dwa razy.** Przekroczenie czasu albo `agent_prompt_stalled` nie dowodzi, że prompt nie dotarł. Przed ponowieniem uruchom `agent read`.

**`agent prompt` zwraca `agent_blocked`.** Agent już stoi na ekranie zgody albo pytania, więc herdr odmawia pisania do niego. Przeczytaj panel, zdecyduj, odpowiedz przez `agent send-keys` i dopiero wtedy wyślij prompt ponownie.

**Agent stał na oknie uprawnień, a pasek boczny pokazywał `idle`.** To powrót do stanu domyślnego przy manifeście ekranu. Potwierdź to przez `herdr agent explain <nazwa>`, a potem pobierz najnowsze reguły przez `herdr server update-agent-manifests`. Powtarzający się kształt okna zgłoś do projektu razem z wynikiem explain w `--json`.

**`agent read --lines 400` zwraca `agent_not_idle`.** Claude Code i OpenCode trzymają historię na alternatywnym ekranie, a herdr umie ją przewijać tylko wtedy, gdy agent jest bezczynny. Poczekaj na `idle` albo czytaj z `--source visible`. Przy długich odpowiedziach każ agentowi zapisać wynik do pliku i przeczytaj plik.

**Porty, `.env` i deweloperska baza danych i tak się zderzyły.** Worktree izoluje tylko pliki, a nowy worktree startuje bez zainstalowanych zależności i bez plików env ignorowanych przez git. Uruchom krok przygotowania (`SETUP_CMD` powyżej) przed agentem i przed każdą bramką, inaczej błąd instalacji wygląda jak `GATE_EXIT=1`. Trzech wykonawców uruchamiających serwer deweloperski na tym samym porcie pokłóci się niezależnie od multipleksera. Daj każdemu worktree własny blok portów albo użyj sandboksa na agenta; zobacz [równoległą pracę agentów](/pl/ecosystem/agent-tools/parallel-agents/).

**Flota wyprzedziła twoje review.** Trzech wykonawców oddaje trzy gałęzie naraz. Liczy się tempo zaakceptowanej pracy, więc dopasuj wielkość floty do tego, co przepuszczą twoje bramki i recenzenci; zobacz [równoległość w zespole](/pl/cto-scorecard-guide/team-parallelism-tier2/) oraz [optymalizację kosztów](/pl/workflows/context/cost-per-context/) od strony limitów.

## Dokąd dalej z herdr

- [Równoległa praca agentów](/pl/ecosystem/agent-tools/parallel-agents/) — Worktree, porty dla każdego worktree i kolejka review dla dziesięciu agentów naraz
- [tmux dla floty agentów](/pl/ecosystem/agent-tools/tmux-for-agent-fleets/) — Te same wzorce w czystym tmuksie: send-keys, capture-pane i wait-for
- [Wzorce orkiestracji wielu agentów](/pl/workflows/automate/orchestration-patterns/) — Kiedy fan-out, potoki i podział na autora i recenzenta się opłacają, a kiedy tylko mnożą koszt
- [Sandboksy dla agentów](/pl/ecosystem/agent-tools/sandboxes/) — E2B, container-use, Daytona i inne, gdy potrzebujesz izolacji wykraczającej poza pliki
- [Worktree Gita dla każdego agenta](/pl/developer-scorecard-guide/git-worktrees/) — Warstwa izolacji pod każdym równoległym przepływem
- [Przegląd narzędzi agentowych](/pl/ecosystem/agent-tools/) — Jakiego rodzaju narzędzia potrzebujesz: powłoki, multipleksera, sandboksa czy bota do review
