AlexK-Notable/claude-skills

Herdr

Herdr organisiert Terminals in Workspaces, Tabs und Panes, erkennt darin laufende Coding-Agenten und macht die aktuelle Sitzung über die herdr CLI zugänglich.

Bevor ein Steuerbefehl erteilt wird, muss überprüft werden, ob dieser Agent in einem Herdr-verwalteten Pane läuft:

test "${HERDR_ENV:-}" = 1

Schlägt die Prüfung fehl, teile mit, dass du nicht in Herdr läufst, und stoppe. Untersuche oder steuere die fokussierte Herdr-Sitzung nicht von außerhalb von Herdr.

Wenn die Prüfung besteht, kommuniziert das herdr-Binary im PATH mit der aktuellen Sitzung. Verwende es, um benachbarte Arbeit zu untersuchen, Terminal-Layouts zu erstellen, Agenten und Befehle zu starten, Ausgaben zu lesen und auf Zustandsänderungen zu warten.

Aktuelle CLI kennenlernen

Das installierte Binary ist die Autorität für die Befehlssyntax. Beginne mit:

herdr --help

Drucke dann die relevante Befehlssgruppe aus, indem du die Gruppe ohne Unterbefehl ausführst:

herdr agent
herdr pane
herdr workspace
herdr tab
herdr worktree
herdr terminal
herdr notification
herdr integration
herdr session

Führe bloßes herdr nicht zur Erkundung aus; es startet oder öffnet die TUI. Untersuche keinen mutierenden verschachtelten Befehl, indem du Argumente weglässt. Befehle wie herdr workspace create sind mit Standardwerten gültig und werden ausgeführt.

Die meisten Steuerbefehle geben JSON zurück. Lies Bezeichner und Zustände aus diesen Antworten, anstatt sie vorherzusagen.

Layout, Panes und Agenten verstehen

Wähle das Primitiv, das zur Aufgabe passt:

• Workspace-, Tab- und Pane-Topologie organisieren Terminal-Positionen.
• Pane-Befehle steuern rohe Terminals, Shells, Tests, Server, Eingabe und Ausgabe.
• Agent-Befehle steuern den erkannten Coding-Agenten, der derzeit ein Pane belegt.

Ein Pane existiert, unabhängig davon, ob es einen Agenten enthält. agent start erfordert ein vorhandenes, verfügbares Shell-Pane und erzeugt, teilt oder verschiebt niemals Layout. Verwende Pane-Befehle für normale Prozesse. Verwende Agent-Befehle, wenn Herdr die Identität des Agenten validieren oder die Lebenszykluszustände idle, working, blocked, done und unknown interpretieren muss.

Agent-Befehle akzeptieren entweder einen eindeutigen, live-Agentennamen oder die Pane-ID, die den Agenten derzeit beherbergt. Sie akzeptieren keine Terminal-IDs oder bloße Agentenart-Bezeichnungen. Namen müssen dem Schema [a-z][a-z0-9_-]{0,31} entsprechen und unter live-Agenten eindeutig sein. Ein Name folgt dem aktuellen Pane-Bewohner und wird gelöscht, wenn dieser Agent beendet, freigegeben oder ersetzt wird.

idle bedeutet, dass der Agent bereit für Eingaben ist und sein Tab in der fokussierten Herdr-Benutzeroberfläche gesehen wurde. done ist derselbe zugrundeliegende Leerlaufzustand, nachdem unsichtbare Hintergrundarbeit abgeschlossen ist. Den Tab fokussieren oder das Pane oder den Agenten mit einem Fokusbefehl anvisieren, markiert es als gesehen. CLI-Lesevorgänge markieren es nicht als gesehen. blocked bedeutet, dass Herdr eine Genehmigungs- oder Frage-Benutzeroberfläche erkannt hat. unknown bedeutet, dass ein Agent vorhanden ist, Herdr ihn aber nicht sicher klassifizieren kann; es beweist keinen Abschluss.

IDs und Aufruferkontext verwenden

Öffentliche IDs sind undurchsichtige, stabile Griffe:

• workspace: w1
• tab: w1:t1
• pane: w1:p1

Geschlossene Tab- und Pane-IDs werden nicht wiederverwendet. Ein in einen anderen Workspace verschobenes Pane erhält eine neue Workspace-qualifizierte Pane-ID. Fahre nach pane move mit .result.move_result.pane.pane_id oder dem live-Agentennamen fort. Der alte Wert wird als .result.move_result.previous_pane_id gemeldet; nur der geerbte Aufruferkontext des verschobenen Prozesses löst diese alte ID weiterhin auf, verwende sie also nicht als allgemeines Agentenziel.

Herdr injiziert den Kontext des Aufrufers in jedes verwaltete Pane:

printf '%s\n' "$HERDR_WORKSPACE_ID" "$HERDR_TAB_ID" "$HERDR_PANE_ID"

Bevorzuge --current, wenn ein Pane-Befehl das aufrufende Pane anvisieren soll. Das Weglassen eines Ziels kann das UI-fokussierte Pane verwenden, das dem Benutzer oder einem anderen Client gehören kann.

Erkunde den Live-Zustand mit:

herdr workspace list
herdr tab list --workspace "$HERDR_WORKSPACE_ID"
herdr pane current --current
herdr pane list --workspace "$HERDR_WORKSPACE_ID"
herdr agent list

Antworten auf Erstellungsbefehle geben die als nächstes zu verwendenden IDs preis. workspace create gibt .result.workspace, .result.tab und .result.root_pane zurück. tab create gibt .result.tab und .result.root_pane zurück. pane split gibt das neue Pane als .result.pane zurück.

Einen Agenten starten und koordinieren

Standardmäßig ein benachbartes Pane im aktuellen Tab und das aktuelle Arbeitsverzeichnis verwenden. Erstelle keinen Workspace, Tab, Worktree oder ein anderes cwd, es sei denn, der Benutzer fordert explizit diese Topologie oder Position an.

Halte eine vom Benutzer angeforderte Richtung ein. Ansonsten untersuche das Aufrufer-Pane:

herdr pane layout --pane "$HERDR_PANE_ID"

Teile ein breites Pane nach rechts und ein schmales oder hohes Pane nach unten. Vermeide wiederholte gleichgerichtete Teilungen, die unbrauchbar schmale Spalten oder kurze Zeilen erzeugen. Behalte den Fokus des Benutzers im aufrufenden Pane und erhalte explizit das Arbeitsverzeichnis des Aufrufers:

herdr pane split --current --direction right --cwd "$PWD" --no-focus

Ersetze right durch down, wenn angemessen. Lies die neue Pane-ID aus .result.pane.pane_id.

Ein verfügbares Shell-Pane muss sich an seinem interaktiven Prompt befinden, wobei die Shell selbst im Vordergrund ist und kein Vordergrundbefehl, Editor oder Agent läuft. Starte einen unterstützten Agenten in diesem Pane mit einem sinnvollen, eindeutigen Namen:

herdr agent start reviewer --kind codex --pane <returned-pane-id>

Verwende die vom Benutzer angeforderte Art. Führe herdr agent aus, um die installierte Artenliste und Optionen zu überprüfen. Übergib native Agentenargumente nur nach --:

herdr agent start reviewer --kind codex --pane <returned-pane-id> -- <agent-args...>

agent start kehrt erst zurück, nachdem Herdr den erwarteten Agenten im selben Pane erkannt und ihn als bereit für interaktive Eingaben betrachtet. Standardmäßig beträgt das Start-Timeout 30 Sekunden.

Reiche Arbeit über die Agentenoberfläche ein:

herdr agent prompt reviewer "Überprüfe den aktuellen Diff und melde nur umsetzbare Erkenntnisse." --wait --timeout 120000

agent prompt sendet atomar Text und codierte Eingabetaste, während der live-Bracketed-Paste-Modus des Panes respektiert wird. Für normale Agentenarbeit reicht --wait: es wartet auf den ersten stabilen Zustand idle, done oder blocked. Wiederhole diese Standardwerte nicht mit --until.

Ein Prompt, der aus einem Nicht-Arbeitszustand gesendet wird, muss innerhalb von fünf Sekunden eine beobachtbare Lebenszyklusänderung bewirken. Andernfalls gibt Herdr agent_prompt_stalled zurück, anstatt unbegrenzt zu warten. Diese Wartezeit verfolgt den Lebenszykluszustand, nicht eine einzelne Runde; wenn der Agent bereits arbeitet, kann die Fertigstellung der aktiven Runde ausreichen.

Verwende --until nur für einen zustandsspezifischen Workflow, z. B. Warten auf einen bereits laufenden Agenten, der eine Eingabe anfordert:

herdr agent wait reviewer --until blocked --timeout 120000

Ohne --until verwendet das eigenständige agent wait dieselben Standardeinstellungen für den stabilen Zustand wie agent prompt --wait.

Verwende logische Tasten für interaktive Agenten-UI-Steuerelemente:

herdr agent send-keys reviewer esc
herdr agent send-keys reviewer ctrl+c

Herdr validiert alle Tasten, bevor Bytes geschrieben werden. Lies das Ergebnis über den aufgelösten Agenten:

herdr agent get reviewer
herdr agent read reviewer --source recent-unwrapped --lines 120

Wenn ein Warten fehlschlägt oder blocked zurückgibt, untersuche agent get und agent read, bevor du entscheidest, welche Eingabe zu senden ist. Verwende die Pane-Oberfläche nur, wenn eine rohe Terminalsteuerung beabsichtigt ist.

Einen normalen Befehl in einem anderen Pane ausführen

Erstelle ein benachbartes Pane mit derselben Geometrieregel, behalte das Arbeitsverzeichnis des Aufrufers bei und lasse den Benutzerfokus unverändert:

herdr pane split --current --direction right --cwd "$PWD" --no-focus

Lies die neue Pane-ID aus .result.pane.pane_id und führe dann den Befehl aus und untersuche ihn:

herdr pane run <returned-pane-id> "just test"
herdr pane wait-output <returned-pane-id> --match "Testergebnis" --timeout 120000
herdr pane read <returned-pane-id> --source recent-unwrapped --lines 120

pane run sendet atomar Befehlstext und Eingabetaste. pane wait-output durchsucht den ausgewählten Schnappschuss sofort, sodass bereits vorhandene Ausgabe übereinstimmen kann. Verwende --match <text> für einen literalen Teilstring oder --regex <muster> für einen Rust-Regulären Ausdruck. Das Weglassen von --timeout erlaubt ein unbegrenztes Warten.

Verwende die Lesequelle, die der Aufgabe entspricht:

• visible: der aktuell gerenderte Ansichtsbereich.
• recent: kürzlich gerenderte Ausgabe, einschließlich weicher Umbrüche.
• recent-unwrapped: kürzliche Ausgabe mit zusammengefügten weichen Umbrüchen; bevorzugt für Logs und Transkripte.
• detection: der Klartext-Bottom-Buffer-Schnappschuss, der für die Agentenerkennung verwendet wird.

Verwende --format ansi, wenn Farben und Terminal-Stil Beweise sind. Andernfalls verwende Text.

--lines fordert Herdr auf, mehr Zeilen aus dem verfügbaren Bildschirm und Host-Scrollback des Panes zu holen. Wenn eine Erhöhung nicht mehr von einer abgeschlossenen Antwort preisgibt, läuft der Agent wahrscheinlich auf dem alternativen Bildschirm des Terminals. Zeilen, die den alternativen Bildschirm verlassen, gelangen nicht in Herdrs Host-Scrollback, sodass eine größere Zeilenanzahl sie nicht wiederherstellen kann.

Nach diesem fehlgeschlagenen Lesevorgang bitte den Agenten, seine vollständige Antwort als Markdown in ein temporäres Verzeichnis zu schreiben und nur den Dateipfad zu antworten, dann lies die Datei direkt. Verwende dies nur als Rückfallebene; fordere keine Dateiausgabe im initialen Prompt an.

Sicherheits- und Koordinationsregeln

• Verwende --no-focus für Hintergrundarbeit, es sei denn, der Benutzer hat gebeten, den Kontext zu wechseln.
• Verwende --current, eine explizite Pane-ID oder einen eindeutigen Agentennamen. Verlasse dich nicht auf das fokussierte Pane eines anderen Clients.
• Analysiere IDs aus JSON-Antworten. Leite sie nicht aus der Seitenleisten-Reihenfolge oder Beispielen ab.
• Schließe keine Workspaces, Tabs, Panes oder Sitzungen, die du nicht erstellt hast, es sei denn, der Benutzer hat es explizit verlangt.
• Führe niemals herdr server stop aus einer aktiven Sitzung aus, es sei denn, der Benutzer beabsichtigt explizit, den Server und seine Pane-Prozesse zu stoppen.
• Töte niemals den Haupt-Herdr-Prozess. Verwende benannte Testsitzungen für Experimente, die einen isolierten Server benötigen.
• CLI-Serverfehler sind JSON auf stderr mit Exit-Status 1. CLI-Syntaxfehler beenden mit Exit-Status 2.

Lokale Redewendungen

Die HERDR_ENV=1-Sperre oben gilt für die Steuerung der aktuellen Sitzung von innerhalb eines Panes. Arbeit auf Host-Ebene – Konfiguration bearbeiten, Plugins installieren, Agentenerkennung debuggen, Automatisierung rund um den Socket/CLI bauen – ist von jedem Terminal aus zulässig. Lies für diese Aufgaben references/local-idioms.md: Benachrichtigungszustellung, Agentenerkennungswartung, Seitenleisten-Metadaten aus Claude Code-Hooks, Ereignisabonnement-Muster, Worktree-Ablauf und Plugin-Erstellungsnotizen.