# herdr-composer Pasek wiadomości dla agentów w [Herdr](https://herdr.dev). Jedno pole pod terminalem pisze do agenta, który ma fokus. Do tego: - drafty per agent, które przetrwają restart, - kolejka czekająca na koniec tury agenta, - historia i ulubione, - dock z przyciskami do często wysyłanych komend (np. `/handoff`), - podpowiedzi `/` i `@`, - jeden sposób dodawania załączników: upuszczenie, przycisk `+`, Ctrl+V. ![herdr-composer](herdr/herdr-composer/preview.png) ## Wymagania - **Windows.** Przycisk `+` i wklejanie obrazów przez Ctrl+V używają PowerShell. Reszta działa wszędzie, gdzie działa Herdr. - **Herdr** (`herdr-app`, `hc`) w `PATH`. Sprawdzone na herdr-core 0.1.21. - **Git** z dostępem do `http://git.mkali.pl/Factor/herdrMario.git` (repo prywatne). Klonowanie użyje Twoich zapisanych poświadczeń. - Do testów: **Node.js ≥ 20**. ## Instalacja Obie drogi dają ten sam wynik. **1. Przez agenta** (tak jak layouty z herdr.dev). Wklej agentowi w Herdr: ```text Read ~/.config/herdr-app/AGENTS.md, then add this layout: clone http://git.mkali.pl/Factor/herdrMario.git and use the folder herdr/herdr-composer ``` **2. Jedną komendą** (`cmd`): ```cmd git clone http://git.mkali.pl/Factor/herdrMario.git "%USERPROFILE%\herdrMario" && "%USERPROFILE%\herdrMario\install.cmd" ``` `install.cmd` uruchamia `scripts\install.ps1` z `-ExecutionPolicy Bypass`, tylko dla tego jednego wywołania. Działa więc także tam, gdzie uruchamianie skryptów `.ps1` jest wyłączone. Instalator: - **Aktualizuje repo:** robi `git pull --ff-only`, ale tylko w czystym klonie. Błąd pull to ostrzeżenie, nie przerwanie. - **Kopiuje mod i layout:** mod trafia do `~\.config\herdr-app\mods\herdr-composer` (kopia lustrzana), layout do `layouts\herdr-composer.json`. Herdr sam wczytuje nowe pliki. Jeśli istnieje inny layout o tej nazwie, najpierw robi jego kopię zapasową. - **Dopisuje skrót** do Twojego `keys.json`: `ctrl-shift-space` przenosi fokus do composera. Przed zapisem robi kopię. Klawisza, który masz przypisany do czegoś innego, nie rusza i wypisuje ostrzeżenie. Formatowanie `keys.json` się zmienia, znaczenie nie. - **Usuwa poprzednią wersję `ovis-composer`:** junction albo katalog modu, layout i skrót. Historia, ulubione, drafty i kolejki zostają (patrz [Przejście z ovis-composer](#przejście-z-ovis-composer)). - **Sprawdza i przełącza:** uruchamia `herdr-app check`. Na layout `herdr-composer` przełącza tylko przy pierwszej instalacji albo wtedy, gdy aktywny był `ovis-composer`. W pozostałych przypadkach podpowiada `ctrl-shift-l`. Wszystkie kopie zapasowe trafiają do `~\.config\herdr-app\backups\herdr-composer\\`, nigdy do `mods\` ani `layouts\`, bo Herdr wczytałby je jako mod lub layout. Pliki repo nigdy nie są usuwane. ## Aktualizacja Uruchom ponownie `install.cmd` albo poproś agenta jeszcze raz. Herdr sam przeładuje mod, bez restartu. ## Odinstalowanie ```cmd install.cmd -Uninstall ``` Usuwa `mods\herdr-composer`, `layouts\herdr-composer.json` i skrót z `keys.json`, a potem przełącza na layout `main`. Zostają tylko kopie w `backups\herdr-composer\`. ## Użycie | Klawisz / akcja | Co robi | |---|---| | klik w pole, `Ctrl+Shift+Space` | fokus w composerze (klik w terminal oddaje klawiaturę terminalowi) | | `Enter` / `Shift+Enter` | wyślij / nowa linia | | `Ctrl+Enter` | wyślij teraz, z pominięciem kolejki | | `Alt+Enter` | do kolejki jako wstrzymana (wyślesz ręcznie) | | `Esc` | zamyka menu lub panel; przy pustym polu przerywa pracującego agenta | | `/`, `@` | podpowiedzi komend, skilli i plików; `↑` `↓` wybór, `Enter`/`Tab` wstaw | | `Ctrl+R` albo 🕘 | panel Historia / Ulubione: `↑` `↓`, `Enter` wstawia w miejscu kursora (bez wysyłania), `Tab` przełącza zakładki, `Ctrl+D` dodaje do ulubionych, `Esc` lub ✕ zamyka | | ☆ | zapisuje bieżący tekst w ulubionych; prawy klik przypina go do docka | | dock (przyciski za ☆) | klik wysyła zapisany tekst do agenta (jak Enter, przez kolejkę) albo, w trybie ✎, wstawia go w miejscu kursora; tekst w polu zostaje | | prawy klik na przycisk docka | Zmień nazwę, Tylko wstawiaj / Wysyłaj od razu, Przesuń w lewo / w prawo, Usuń z docka | | prawy klik na wiersz panelu | Wstaw, Dodaj do ulubionych / Usuń z ulubionych; w Ulubionych także Przypnij do docka / Odepnij z docka | | `+`, upuszczenie pliku, `Ctrl+V` obrazu | załącznik: kopiowany do agenta przez `hc put` i dopisywany jako `@ścieżka` | **Kolejka:** gdy agent pracuje, `Enter` dodaje wiadomość do kolejki. Po zakończeniu tury pojawia się odliczanie 3 s z przyciskiem Anuluj, a potem wiadomość wychodzi. Stop albo `Esc` wstrzymuje całą kolejkę. Gdy agent czeka na Twoją odpowiedź (`blocked`), `Enter` wysyła ją od razu (`hc send --force`). **Dock:** wspólny dla wszystkich agentów, do 30 przycisków. Przyciski dodajesz prawym klikiem na wpis w Ulubionych („Przypnij do docka”) albo na ☆ (bieżący tekst). Gdy przycisków jest dużo, dock przewija się w bok. **Dane:** historia (500 wpisów), ulubione (100), dock (30 przycisków), drafty i kolejki zapisują się lokalnie w `~\.config\herdr-app\shared.json` (klucze `herdr-composer.*`). Obrazy ze schowka trafiają do `~\.config\herdr-app\data\herdr-composer\paste\` i są usuwane po 7 dniach. Nic nie jest wysyłane poza ten komputer. ## Inni agenci Menu `/` podpowiada komendy według **profilu agenta**. Domyślne profile są dla Claude Code (alias `claude`) i `codex`. Dla innego agenta menu pokazuje komendy, które wysłałeś mu wcześniej (grupa „Z historii”) oraz szary wiersz „Nieznany agent `` – dodaj profil w ~/.config/herdr-app/composer-agents.json”. Klucz z tego wiersza wpisz w polu `match`. Profile dopisujesz w pliku `~\.config\herdr-app\composer-agents.json` (albo `$HERDR_APP_HOME\composer-agents.json`) na komputerze, na którym działa agent. Zmiana pojawia się w menu w ciągu minuty, bez restartu i bez reinstalacji. ```json { "agents": [ { "id": "nazwa-profilu", "match": ["klucz-agenta"], "builtins": [{ "key": "model", "desc": "Wybiera model." }], "sources": [ { "scope": "project", "path": ".agent/prompts", "pattern": "*.md" }, { "scope": "home", "path": ".agent/prompts", "pattern": "*/SKILL.md", "prefix": "@" } ] } ] } ``` - `id` (wymagany): nazwa profilu. Profil z tym samym `id` co domyślny **zastępuje go w całości**, bez łączenia list. - `match` (wymagany, niepusta lista): klucze agenta, bez rozróżniania wielkości liter. Najpierw sprawdzane są profile z pliku, potem domyślne. - `builtins` (opcjonalny): `{ "key", "desc" }`, grupa „Wbudowane”. - `sources` (opcjonalny): `scope` to `"project"` (względem folderu panelu; grupa „Projekt”) albo `"home"` (względem folderu domowego; grupa „Użytkownik”). `path` jest względna, bez `..`. `pattern` to `"*.md"` (nazwa komendy = nazwa pliku bez `.md`) albo `"*/SKILL.md"` (nazwa skilla z `name:` we frontmatterze, a w projekcie z nazwy folderu). `prefix` (domyślnie `"/"`) to tekst wstawiany przed nazwą. Źródło `{ "scope": "home", "kind": "claude-plugins" }` czyta pluginy Claude Code. - Brak pliku to norma. Uszkodzony plik jest ignorowany (działają profile domyślne), a menu pokazuje wiersz „`composer-agents.json`: ”. **Przykład dla kiro-cli: niesprawdzony.** Nie znamy klucza ani komend tego agenta, więc poniższe wartości są tylko ilustracją. Klucz weź z wiersza „Nieznany agent …” na maszynie z kiro. ```json { "agents": [ { "id": "kiro", "match": ["kiro-cli", "kiro"], "builtins": [{ "key": "context" }, { "key": "model" }], "sources": [ { "scope": "project", "path": ".kiro/prompts", "pattern": "*.md" }, { "scope": "home", "path": ".kiro/prompts", "pattern": "*.md", "prefix": "@" } ] } ] } ``` ## Co mod uruchamia i czyta Agent instalujący paczkę poinformuje o tym przed instalacją. - **`hc`:** `send`, `put`, `get`, `interrupt`, `keys`. Tak mod rozmawia z terminalami agentów. - **`powershell`:** odczyt schowka, okno wyboru pliku, rozmiary plików, odczyt komend i skilli z folderów projektu wskazanych w profilu agenta (dla Claude Code `.claude/`). Ścieżki trafiają do skryptów wyłącznie jako Base64. - **`git ls-files`** w folderze agenta: podpowiedzi `@`. - **Pliki spoza folderu modu:** pliki, które sam dodajesz jako załączniki, foldery komend z profilu agenta (dla Claude Code `.claude/commands`, `.claude/skills` projektu i `~\.claude`) oraz `composer-agents.json` w `~\.config\herdr-app\`. - **Sieć:** mod nie korzysta z sieci. ## Przejście z ovis-composer Wcześniejsza wersja nazywała się `ovis-composer`. Instalator usuwa ją automatycznie. Mod przy pierwszym odczycie przenosi dane z kluczy `ovis-composer.*` do `herdr-composer.*`; starych kluczy nie kasuje. Instalator nie rusza starych kopii `mods\ovis-composer.bak-*` i `layouts\ovis-composer.json.bak-*`. Możesz je usunąć ręcznie. ## Rozwiązywanie problemów - **Composer się nie pokazuje:** sprawdź `herdr-app status`. Pole `"layout"` powinno mieć wartość `herdr-composer`, a `"errors"` powinno być puste. Layout przełączysz przez `ctrl-shift-l`. - **Mod nie reaguje po zmianie plików:** uruchom ponownie `install.cmd`. Herdr widzi tylko pliki w `~\.config\herdr-app\mods\`, a nie te w repo. - **`Ctrl+Shift+Space` nie działa:** sprawdź, czy w `~\.config\herdr-app\keys.json` (sekcja `global`) jest `"ctrl-shift-space": "herdr-composer.focus"` i czy obok nie powstał plik `keys.error`. - **Coś nie gra po instalacji:** `install.cmd -Uninstall`, a potem przywróć potrzebny plik z `backups\herdr-composer\`. Awaryjnie `ctrl-alt-shift-escape` zawsze wraca do layoutu `main`. ## Rozwój Struktura repo: - `herdr/herdr-composer/`: paczka w formacie Herdr (`layouts/`, `mods/herdr-composer/`, `keys.json`, `RECIPE.md`, `preview.png`). - `tests/`: testy czystych modułów (`npm test`). - `scripts/install.ps1`: instalator, wywoływany przez `install.cmd`. - `docs/superpowers/`: specyfikacja, plany, makieta, raporty weryfikacji. Cykl pracy: edytuj pliki w `herdr/herdr-composer/mods/herdr-composer/`, uruchom `npm test`, potem `install.cmd`, żeby skopiować zmianę do Herdr. Problemy pokażą `herdr-app check "%USERPROFILE%\.config\herdr-app\mods\herdr-composer"` i `herdr-app status`.