Przewodnik herdr

Start

Jak działa herdr

herdr to menedżer terminali dla agentów AI, podobny do tmux. Działa jako serwer w tle, więc panele i agenci pracują dalej, gdy zamkniesz okno. Do tego rozpoznaje agentów w panelach i pokazuje ich stan w panelu bocznym. Działa na macOS, Linuksie i Windows.

Od zwykłego terminala do herdr

1. Agent w zwykłym terminalu. Otwierasz terminal, uruchamiasz claude i pracujesz. Działa to tak długo, jak otwarte jest okno: zamkniesz je albo zerwie się połączenie SSH, a agent kończy pracę razem z nim. Przy kilku agentach masz kilka okien i klikasz po kolei, żeby sprawdzić, który na ciebie czeka.

2. tmux. Sesja należy do serwera tmux, a nie do okna, więc okno możesz zamknąć, a agent pracuje dalej. Dostajesz też panele i karty. Tylko że tmux widzi w panelach sam tekst: dla niego Claude to jeszcze jeden program i nie wie, czy pracuje, czy czeka na twoją zgodę.

3. herdr. Robi to samo co tmux, a do tego rozpoznaje agentów w panelach i pokazuje ich stan w pasku bocznym. Obsługujesz go myszką, a agenci mogą nim sterować przez komendy herdr. Panele trzyma serwer działający w tle, a okno terminala jest tylko widokiem na nie.

Stany agenta w panelu bocznym

Start

Instalacja

1. Zainstaluj herdr w Terminalu albo iTerm2. Plik trafia do ~/.local/bin/herdr. Możesz też użyć brew install herdr.

   TerminalKopiuj

   curl -fsSL https://herdr.dev/install.sh | sh

2. Sprawdź wersję. Jeśli system nie znajduje polecenia, otwórz terminal ponownie.

   herdr --version

3. Uruchom w katalogu projektu. Przy pierwszym starcie przejdziesz onboarding: motyw, powiadomienia i integracje agentów.

   cd ~/Developer/moj-projekt
   herdr

4. Aktualizacje robisz jedną komendą. Działające panele zostają. Przy instalacji z Homebrew aktualizujesz przez brew upgrade herdr.

   herdr update

1. Zainstaluj Windows Terminal, jeśli go nie masz (w Windows 11 jest wbudowany). Na nim herdr jest testowany, a stary wiersz poleceń konsoli działa gorzej.

   PowerShellKopiuj

   winget install Microsoft.WindowsTerminal

2. Zainstaluj herdr w PowerShellu. Instalator dopisuje herdr do PATH.

   PowerShellKopiuj

   powershell -ExecutionPolicy Bypass -c "irm https://herdr.dev/install.ps1 | iex"

   Jeśli antywirus albo polityka firmy zablokuje to polecenie, użyj wersji dla wiersza poleceń (cmd):

   cmdKopiuj

   curl.exe -fsSLo install.cmd https://herdr.dev/install.cmd && install.cmd && del install.cmd

3. Otwórz nowe okno terminala i sprawdź wersję.

   herdr --version

4. Uruchom w katalogu projektu. Przy pierwszym starcie przejdziesz onboarding.

   cd $HOME\Projects\moj-projekt
   herdr

5. Aktualizacje robisz jedną komendą. Nowe instalacje są na kanale stable. Jeśli kiedyś instalowałeś wersję preview, przełącz się poleceniem herdr channel set stable.

   herdr update

Start

Pierwsze kroki

1. Uruchom agenta w panelu: claude albo codex. herdr sam go wykryje i pokaże jego stan w panelu bocznym.

2. Podziel ekran: ctrl+b v w prawo, ctrl+b - w dół. W drugim panelu uruchom testy albo serwer.

3. Używaj myszy. Kliknięcie przenosi do panelu, przeciągnięcie krawędzi zmienia rozmiar, prawy przycisk otwiera menu, a zaznaczenie tekstu kopiuje go.

   Wklejanie w Windows Terminal: ctrl+shift+v. shift + prawy przycisk włącza wklejanie samego terminala.

4. Odłącz się przez ctrl+b q albo zamknij okno terminala. Agenci pracują dalej. Wracasz poleceniem herdr.

Start

Skróty 80/20

Na macOS i Windows skróty są takie same. Każdy zaczyna się od prefiksu: naciśnij ctrl+b, puść, potem klawisz akcji. Na macOS to klawisz Control, nie Command.

Najważniejsze

Karty, panele i tekst

Konfiguracja

Plik config.toml

Konfiguracja jest w pliku ~/.config/herdr/config.toml%APPDATA%\herdr\config.toml. Dokładną ścieżkę pokazuje herdr --help. herdr działa bez tego pliku, a błędna wartość nie psuje startu: herdr bierze wartość domyślną i pokazuje ostrzeżenie.

mkdir -p ~/.config/herdr
open -e ~/.config/herdr/config.toml

New-Item -ItemType Directory -Force "$env:APPDATA\herdr" | Out-Null
notepad "$env:APPDATA\herdr\config.toml"

• Pełna konfiguracja domyślna z opisami: herdr --default-config
• Wczytanie zmian bez restartu: herdr server reload-config albo ctrl+b shift+r
• Przed większą zmianą zrób kopię pliku

Sprawdzona konfiguracja startowa

onboarding = false

[theme]
name = "nord"

[ui]
# agenci wg pilności: blocked → working → done → idle
agent_panel_sort = "priority"
# kształty zamiast samych kolorowych kropek
status_indicators = "symbols"
# nazwa agenta na krawędzi panelu
show_agent_labels_on_pane_borders = true

[ui.toast]
delivery = "system"     # powiadomienia systemowe

Skrót do wtyczki file viewer dopisujesz po jej instalacji, zob. Wtyczki.

Konfiguracja

Kolory i motywy

Motyw ustawiasz w sekcji [theme]. Wbudowane motywy:

terminal bierze kolory z profilu twojego terminala (iTerm2, Terminal, GhosttyWindows Terminal, WezTerm, Alacritty).

Automatyczny jasny i ciemny tryb

herdr przełącza motyw razem z jasnym lub ciemnym wyglądem terminala.

[theme]
auto_switch = true
dark_name = "catppuccin"
light_name = "catppuccin-latte"

Własne kolory na bazie motywu

W [theme.custom] nadpisujesz pojedyncze kolory. Działa zapis hex, nazwy kolorów i rgb(r,g,b). Dostępne pola: sidebar_bg, active_row_bg, selection_bg, panel_bg, accent, text, red, green, blue, yellow.

[theme.custom]
accent = "#88c0d0"
sidebar_bg = "#2e3440"
panel_bg = "reset"      # tło paneli = tło terminala

# osobne nadpisania dla trybów, gdy auto_switch = true
[theme.custom.light]
panel_bg = "#eceff4"

Konfiguracja

Powiadomienia i dźwięk

Dźwięk gra domyślnie, gdy agent w tle skończy pracę albo czeka na ciebie. Dymki ustawiasz w [ui.toast]:

1. Zainstaluj terminal-notifier. Bez niego powiadomienia przychodzą jako „Script Editor” i kliknięcie w nie nie przenosi do terminala.

   brew install terminal-notifier

2. Daj zgodę na powiadomienia: Ustawienia systemowe → Powiadomienia → terminal-notifier. Jeśli go tam nie ma, wyślij jedno powiadomienie testowe:

   terminal-notifier -title herdr -message test

1. Nic nie instalujesz. Powiadomienia systemowe i dźwięki mp3 działają w Windows od razu.

2. Sprawdź zgodę: Ustawienia → System → Powiadomienia. Muszą być włączone dla terminala. Wyłącz też tryb „Nie przeszkadzać”, jeśli chcesz je widzieć w trakcie pracy.

3. Kliknięcie w powiadomienie przenosi do panelu agenta, o ile okno herdr jest otwarte.

Własne dźwięki (mp3) ustawiasz kluczami [ui.sound] done_path i request_path.

Konfiguracja

Terminal i klawiatura

Opcjonalnie: skróty bez prefiksu

[keys]
focus_pane_left  = ["prefix+h", "ctrl+alt+h"]
focus_pane_down  = ["prefix+j", "ctrl+alt+j"]
focus_pane_up    = ["prefix+k", "ctrl+alt+k"]
focus_pane_right = ["prefix+l", "ctrl+alt+l"]
split_vertical   = ["prefix+v", "ctrl+alt+d"]
new_tab          = ["prefix+c", "ctrl+alt+c"]
zoom             = ["prefix+z", "ctrl+alt+z"]

[keys]
focus_pane_left  = ["prefix+h", "ctrl+alt+h"]
focus_pane_down  = ["prefix+j", "ctrl+alt+j"]
focus_pane_up    = ["prefix+k", "ctrl+alt+k"]
split_vertical   = ["prefix+v", "ctrl+alt+d"]
new_tab          = ["prefix+c", "ctrl+alt+t"]
zoom             = ["prefix+z", "ctrl+alt+m"]

Konfiguracja

Wtyczki

Wtyczki są na GitHubie pod tagiem herdr-plugin. herdr ich nie sprawdza ani nie izoluje: działają z twoimi uprawnieniami. Zanim zainstalujesz wtyczkę, przeczytaj jej herdr-plugin.toml i skrypty, a instalację przypnij do commita, który przeczytałeś.

File viewer: drzewo plików i diffy

1. Programy do podglądu: diffy (delta), kod (bat) i markdown (glow).

   brew install git-delta bat glow

   PowerShellKopiuj

   winget install dandavison.delta sharkdp.bat charmbracelet.glow

2. Instalacja przypięta do przejrzanego commita.

   herdr plugin install smarzban/herdr-file-viewer --ref <commit>

3. Dopisz skróty do config.toml, potem herdr server reload-config. Na Windows wtyczka ma osobne akcje z końcówką -windows.

   config.toml (macOS)Kopiuj

   [[keys.command]]
   key = "prefix+f"
   type = "plugin_action"
   command = "herdr-file-viewer.open-file-viewer"
   description = "file viewer (split)"
   
   [[keys.command]]
   key = "prefix+shift+f"
   type = "plugin_action"
   command = "herdr-file-viewer.open-file-viewer-tab"
   description = "file viewer (tab)"

   config.toml (Windows)Kopiuj

   [[keys.command]]
   key = "prefix+f"
   type = "plugin_action"
   command = "herdr-file-viewer.open-file-viewer-windows"
   description = "file viewer (split)"
   
   [[keys.command]]
   key = "prefix+shift+f"
   type = "plugin_action"
   command = "herdr-file-viewer.open-file-viewer-tab-windows"
   description = "file viewer (tab)"

herdr plugin list
herdr plugin action list --plugin herdr-file-viewer
herdr plugin update

Claude i agenci

Integracje agentów

Integracja to hook w ustawieniach agenta. Dzięki niej herdr dokładnie zna stan agenta i po restarcie serwera wznawia jego rozmowę.

herdr integration install claude
herdr integration install codex
herdr integration status

Na Windows integracje obsługują węższą grupę agentów niż na macOS: m.in. Claude Code, Codex, Pi i OpenCode.

Jeśli agent pokazuje zły stan albo nie jest wykryty, sprawdź herdr agent list, a potem herdr agent explain <panel> --json.

Claude i agenci

Skill herdr dla Claude

Oficjalny skill uczy Claude komend herdr: dzielenia paneli, uruchamiania innych agentów, czytania ich wyników i czekania na zmiany stanu. Działa tylko wtedy, gdy Claude pracuje w panelu herdr (zmienna HERDR_ENV=1).

1. Zainstaluj skill z binarki herdr. Bez pobierania z internetu, zawsze w wersji zgodnej z twoim herdr.

   TerminalKopiuj

   mkdir -p ~/.claude/skills/herdr
   herdr --skill > ~/.claude/skills/herdr/SKILL.md

   PowerShell (zapis w UTF-8 bez BOM)Kopiuj

   New-Item -ItemType Directory -Force "$HOME\.claude\skills\herdr" | Out-Null
   [IO.File]::WriteAllLines("$HOME\.claude\skills\herdr\SKILL.md", (herdr --skill))

2. Po każdym herdr update powtórz drugą linię, żeby skill pasował do nowej wersji.

3. Wywołuj go wprost. Skill włącza się, gdy w prośbie pada słowo „herdr”. Przykłady znajdziesz w sekcji Gotowe prompty.

Claude i agenci

Zasady w CLAUDE.md

Skill mówi Claude, jakich komend użyć, a te zasady mówią, jak to robić porządnie. Wklej je do globalnego pliku ~/.claude/CLAUDE.md%USERPROFILE%\.claude\CLAUDE.md (wszystkie projekty) albo do CLAUDE.md w konkretnym repozytorium.

## herdr — praca w panelach (gdy HERDR_ENV=1)

Szczegóły komend: skill `herdr`. Te zasady mówią, JAK z nich korzystać.

**Nazewnictwo**
- Każdy uruchamiany agent dostaje nazwę roli: `herdr agent start <rola> --kind claude|codex --pane <id>`.
  Role: `impl-<zadanie>`, `review`, `test`, `codex-review`, małymi literami.
- Panel z procesem bez agenta (serwer, testy, logi) podpisz: `herdr pane rename <pane_id> "dev server"`.
- Nowa karta = jeden etap pracy, od razu nazwana: `herdr tab rename <tab_id> "etap 2"`.

**Układ**
- Pracuj w bieżącej karcie i katalogu. Nowy workspace, kartę lub worktree tylko na moją prośbę
  albo gdy zadania równolegle dotykają tych samych plików.
- Szeroki panel dziel w prawo, wąski w dół. Maksymalnie 3–4 panele w karcie.
- Zawsze `--no-focus`: nie zabieraj mi fokusu.
- ID bierz z JSON-a odpowiedzi, nigdy nie zgaduj.

**Koordynacja**
- Prompt z `--wait --timeout <ms>`, wynik czytaj: `herdr agent read <nazwa> --source recent-unwrapped`.
- `blocked` = agent pyta o zgodę: pokaż mi pytanie, nie odpowiadaj za mnie.
- Timeout nie oznacza, że prompt nie doszedł: najpierw przeczytaj panel, potem ponawiaj.
- Po długim zadaniu: `herdr notification show "<tytuł>" --body "<co dalej>" --sound done`.

**Sprzątanie**
- Zamykaj tylko panele i karty, które sam utworzyłeś, po zakończeniu ich pracy. Moich nigdy.
- Nie uruchamiaj `herdr server stop` i nie ubijaj procesu herdr.

Claude i agenci

Gotowe prompty

Wpisujesz je w Claude Code uruchomionym w panelu herdr. Słowo „herdr” w prośbie włącza skill. Działają tak samo na macOS i Windows.

VPS i zdalnie

Wdrożenie na VPS

Na VPS-ie z Linuksem herdr działa 24/7, więc agenci pracują nawet przy wyłączonym komputerze. Łączysz się z nim z macOS, Windows albo telefonu. Działające sesje nie przenoszą się z komputera: na serwerze stawiasz herdr od nowa i klonujesz repozytoria.

Najszybciej: jeden prompt dla Claude

Wklej ten prompt do Claude Code na swoim komputerze. Claude znajdzie VPS przez Hostinger MCP, dobierze komendy do twojego systemu i przeprowadzi całe wdrożenie. O hasła i logowania poprosi ciebie, a przed każdą ryzykowną zmianą zapyta o zgodę.

Potrzebujesz: Claude Code z podłączonym Hostinger MCP (plugin hostinger) albo, bez MCP, adresu IP serwera. Na samym komputerze herdr musi być już zainstalowany.

Wdróż herdr na moim VPS-ie, żebym mógł łączyć się z nim z lokalnego herdr.
VPS znajdź przez Hostinger MCP (bez MCP zapytaj mnie o adres).
Dopasuj komendy do mojego systemu. Mów krótko, po polsku.

1. Rozpoznanie (tylko odczyt): co działa na serwerze, czy ktoś loguje się hasłem.
   Nie ruszaj Dockera ani działających usług.
2. Osobny użytkownik dev bez sudo i bez dostępu do Dockera, logowanie kluczem,
   u mnie alias SSH "herdr-vps".
3. Zabezpieczenia: logowanie do SSH tylko kluczem i firewall ufw.
   Najpierw pokaż plan i poczekaj na moje "tak".
4. Dla dev: Node LTS, Claude Code, Codex, herdr i integracje herdr dla claude i codex.
5. herdr jako usługa systemd --user, działająca 24/7 także po restarcie serwera,
   z konfiguracją jak u mnie lokalnie.
6. Podepnij serwer: herdr machine add herdr-vps --label vps i sprawdź połączenie.

Jako podsumowanie zwróć krótką tabelę, co zrobiłeś i sprawdziłeś, oraz co zostało
dla mnie (logowanie claude i codex na serwerze, dostęp do GitHuba).

Krok po kroku, ręcznie

1. Na swoim komputerze wygeneruj klucz dla serwera i wyświetl jego część publiczną.

   TerminalKopiuj

   ssh-keygen -t ed25519 -C "herdr-vps-dev" -f ~/.ssh/id_ed25519_herdr_vps
   cat ~/.ssh/id_ed25519_herdr_vps.pub

   PowerShell (OpenSSH jest wbudowany w Windows 10/11)Kopiuj

   ssh-keygen -t ed25519 -C "herdr-vps-dev" -f "$HOME\.ssh\id_ed25519_herdr_vps"
   Get-Content "$HOME\.ssh\id_ed25519_herdr_vps.pub"

2. Na serwerze jako root załóż użytkownika dev, bez sudo i bez grupy docker. Grupa docker to w praktyce dostęp roota.

   VPS, rootKopiuj

   adduser --disabled-password --gecos '' dev
   install -d -m 700 -o dev -g dev /home/dev/.ssh
   nano /home/dev/.ssh/authorized_keys      # wklej klucz .pub
   chown dev:dev /home/dev/.ssh/authorized_keys
   chmod 600 /home/dev/.ssh/authorized_keys
   loginctl enable-linger dev               # usługi dev działają bez logowania

3. Na swoim komputerze dodaj alias SSH w pliku ~/.ssh/config%USERPROFILE%\.ssh\config i sprawdź logowanie: ssh herdr-vps.

   .ssh/configKopiuj

   Host herdr-vps
       HostName <adres-IP-VPS>
       User dev
       IdentityFile ~/.ssh/id_ed25519_herdr_vps
       IdentitiesOnly yes
       ServerAliveInterval 30
       ServerAliveCountMax 3

   Zapis ~/.ssh/... działa też w OpenSSH na Windows. Plik zapisz bez rozszerzenia, nie jako config.txt.

4. Jako dev zainstaluj narzędzia w katalogu domowym. Node bierzesz z oficjalnej paczki LTS z nodejs.org, rozpakowanej do ~/.local/node (sprawdź sumę SHA-256).

   VPS, devKopiuj

   echo 'export PATH="$HOME/.local/bin:$HOME/.local/node/bin:$PATH"' >> ~/.bashrc
   source ~/.bashrc
   npm config set prefix "$HOME/.local"
   npm install -g @openai/codex
   curl -fsSL https://claude.ai/install.sh | bash
   curl -fsSL https://herdr.dev/install.sh | sh
   herdr integration install claude
   herdr integration install codex

5. Uruchom herdr jako usługę systemd, żeby wstawał sam po restarcie serwera.

   ~/.config/systemd/user/herdr.serviceKopiuj

   [Unit]
   Description=herdr headless server (default session)
   After=network-online.target
   
   [Service]
   Type=simple
   WorkingDirectory=%h/projects
   Environment=PATH=%h/.local/bin:%h/.local/node/bin:/usr/local/bin:/usr/bin:/bin
   Environment=SHELL=/bin/bash
   ExecStart=%h/.local/bin/herdr server
   Restart=on-failure
   RestartSec=5
   
   [Install]
   WantedBy=default.target

   VPS, devKopiuj

   mkdir -p ~/projects
   systemctl --user daemon-reload
   systemctl --user enable --now herdr.service
   systemctl --user status herdr.service

6. Zaloguj agentów na serwerze: claude, potem codex login. Logowanie robisz sam, bo wymaga twoich danych.

Konfiguracja herdr na serwerze

onboarding = false

[theme]
name = "nord"

[terminal]
new_cwd = "~/projects"

[ui]
agent_panel_sort = "priority"
status_indicators = "symbols"

[ui.toast]
delivery = "herdr"      # serwer nie ma pulpitu

[experimental]
pane_history = true     # zawartość paneli przetrwa restart

VPS i zdalnie

SSH i firewall

Agenci z dostępem do powłoki na serwerze z produkcją wymagają porządnie zabezpieczonego wejścia. Zrób te dwa kroki przed pierwszym uruchomieniem agentów. Wszystkie komendy wykonujesz na serwerze, więc są takie same niezależnie od twojego systemu.

Logowanie tylko kluczem

Przed zmianą sprawdź w logach, czy ktoś loguje się hasłem: zgrep "Accepted password" /var/log/auth.log*. Plik z prefiksem 00- wygrywa z ustawieniami cloud-init, bo w sshd liczy się pierwsza znaleziona wartość.

PasswordAuthentication no
KbdInteractiveAuthentication no
PermitRootLogin prohibit-password
PermitEmptyPasswords no
MaxAuthTries 4

sshd -t && systemctl reload ssh

ufw z automatycznym wycofaniem

Timer wyłączy ufw po 3 minutach, gdybyś stracił dostęp. Gdy wszystko działa, zatrzymaj go.

systemd-run --unit=ufw-rollback --on-active=180 /usr/sbin/ufw --force disable
ufw default deny incoming
ufw default allow outgoing
ufw allow 22/tcp  comment "SSH (tylko klucze)"
ufw allow 80/tcp  comment "HTTP"
ufw allow 443/tcp comment "HTTPS"
ufw allow in on tailscale0 comment "Tailscale"   # jeśli używasz
ufw --force enable
# test nowego logowania w osobnym oknie, potem:
systemctl stop ufw-rollback.timer

VPS i zdalnie

Agenci a kontenery

Na serwerze działają dwa oddzielne światy. Produkcja żyje w Dockerze roota. herdr i agenci działają jako użytkownik dev, który nie ma dostępu do Dockera.

VPS
├── Docker (root)            # produkcja: twoje aplikacje, reverse proxy
└── użytkownik dev           # bez sudo, bez grupy docker
    ├── herdr.service        # herdr i agenci
    └── ~/projects/<repo>    # klony repozytoriów, na nich pracują agenci

Dlaczego bez dostępu do Dockera

• Grupa docker to w praktyce root. Kto może uruchomić kontener, może zamontować cały dysk serwera i zmienić w nim wszystko.
• Agent popełnia błędy jak każdy. Źle zrozumiane polecenie albo prompt injection z czytanej strony nie powinny móc zatrzymać produkcji ani skasować bazy.
• Oddzielenie ułatwia sprawdzanie. Każda zmiana przechodzi przez gita, więc widzisz diff, zanim trafi na produkcję.

Na czym pracują agenci

VPS jest dla agentów osobnym środowiskiem pracy, takim jak twój laptop, tylko działającym 24/7. Klonujesz repozytoria do ~/projects, agenci zmieniają kod, uruchamiają testy i wypychają zmiany do gita. Do kontenerów zmiany trafiają tą samą drogą co z laptopa.

1. Agent pracuje na klonie w ~/projects/<repo>: edytuje, testuje, robi commit na osobnej gałęzi.

2. Wypycha gałąź i otwiera PR. Serwer potrzebuje do tego klucza z dostępem tylko do wybranych repozytoriów.

3. Wdrożenie idzie twoją zwykłą drogą, np. przez CI po scaleniu PR-a.

VPS i zdalnie

Podpięcie remote

1. Na swoim komputerze zapisz serwer jako maszynę. Robisz to raz.

   TerminalKopiuj

   herdr machine add herdr-vps --label vps
   herdr machine status vps

2. Uruchom herdr lokalnie. Połączenie z serwerem zestawia się samo w tle, a w panelu bocznym pojawia się sekcja „vps” z jej workspace'ami.

3. Przełączaj się przez ctrl+b w i Enter na workspace z „vps”. Nowe karty i panele powstają wtedy na serwerze.

Na Windows herdr korzysta z wbudowanego klienta OpenSSH. Nie współdzieli jednego połączenia jak na macOS, więc pierwsze połączenie po starcie trwa chwilę dłużej. Klucz z hasłem dodaj najpierw do agenta: ssh-add $HOME\.ssh\id_ed25519_herdr_vps (wymaga włączonej usługi „OpenSSH Authentication Agent”).

Gdy maszyna pokazuje „Attention”, uruchom herdr machine status vps, a przy problemie z logowaniem herdr machine reconnect vps.

Pomoc

Na co uważać

• Logi: ~/.config/herdr/%APPDATA%\herdr\, pliki herdr-server.log i herdr-client.log
• Stan klienta i serwera: herdr status
• Dokumentacja: herdr.dev/docs, osobno herdr na Windows