Multiplexer

Collie steuert pro Installation einen Multiplexer an: Herdr, tmux oder zellij. Herdr ist der Standard. Diese Seite beschreibt die Konfiguration von Collie für alle drei Optionen, die Abfragemöglichkeiten der Backends und die Beacons, mit denen Collie Agenten in einem Pane erkennt.

Collie auf einen Multiplexer ausrichten

Benennen Sie das Backend in COLLIE_MUX, verweisen Sie auf einen Endpunkt, starten Sie neu und installieren Sie die Beacon-Hooks.

Experimentell in 1.0. tmux und zellij wurden unter tmux 3.6b und zellij 0.44.2 auf einem einzelnen Host getestet. Herdr ist das standardmäßige und primär unterstützte Backend. Tester gesucht: Erstellen Sie ein Issue auf AltanS/collie mit dem Titel tmux: … oder zellij: … sowie Angaben zu Multiplexer, Version, Betriebssystem und dem beobachteten Verhalten.

Geben Sie den Multiplexer in der Befehlszeile an:

COLLIE_MUX=herdr collie start
COLLIE_MUX=tmux collie start
COLLIE_MUX=zellij collie start

Geben Sie den Endpunkt an, falls das Standardziel abweicht:

# in your .env: ~/.config/collie/.env, or Herdr's plugin config dir on a Herdr
# install. See Configure for the full precedence.
COLLIE_MUX=tmux
COLLIE_MUX_ENDPOINT_TMUX=/run/user/1000/collie-tmux.sock
COLLIE_MUX_ENDPOINT_ZELLIJ=collie-zellij

# only if the binary sits somewhere unusual
# COLLIE_TMUX_BIN=/usr/bin/tmux
# COLLIE_ZELLIJ_BIN=/home/you/.local/bin/zellij

Herdr hat hier keine Endpunkt-Variable: Sein Socket ist HERDR_SOCKET_PATH, kein COLLIE_MUX_ENDPOINT_-Name.

Dieser Socket ist der lokale und kein anderer. Herdr 0.9.0 kann SSH-Maschinen speichern und mehrere Server in einem Herdr-Client anzeigen. Collie liest keinen davon aus, sodass eine in Herdr gespeicherte Maschine kein pack-Mitglied ist; nur ein Collie-pack bringt die Sitzungen einer anderen Maschine auf das Smartphone.

Starten Sie anschließend neu, installieren Sie die Beacon-Hooks und starten Sie einen Agenten im Sichtbereich des Telefons:

collie restart                 # after every .env edit
collie hooks install claude    # once per host, tmux and zellij only

# open a window or a tab for the agent
tmux -S /run/user/1000/collie-tmux.sock new-window -n claude
zellij --session collie-zellij action new-tab --name claude

claude                         # in that window or tab

Wirkung dieser Befehle

COLLIE_MUX in der Befehlszeile legt die Auswahl für diese und jede spätere Ausführung fest. start schreibt den Namen in .env, sodass spätere Ausführungen von collie start denselben Multiplexer steuern.

Wenn COLLIE_MUX nicht gesetzt ist, sucht start nach Herdr, tmux und zellij, fragt nach einem Backend und schreibt die Antwort in .env. Die vollständige Konfigurationsreferenz finden Sie unter MUX_CONTRACT.md → Collie auf einen Multiplexer ausrichten.

collie hooks install claude installiert die Beacon-Hooks von Collie, die tmux und zellij benötigen. Sie stellen Panes als generische Shells bereit, sodass ohne Hooks jedes Pane als bash erscheint.

Der Befehl aktualisiert ~/.claude/settings.json und belässt Projektkonfigurationen unverändert (Details unten). Laufende Claude-Instanzen laden ihre Konfiguration nicht neu; starten Sie diese daher neu.

Hinweis. Herdr ist in diesem Modus nicht erforderlich. Mit COLLIE_MUX=tmux oder COLLIE_MUX=zellij lädt die Bridge nur den ausgewählten Adapter und ignoriert den Socket von Herdr. Die Erkennung mehrerer Sitzungen über Herdr-Konfigurations-Roots hinweg ist deaktiviert (bridge/index.ts). Sie müssen Herdr weder installiert haben noch ausführen, und .env befindet sich in ~/.config/collie/ statt im Plugin-Konfigurationsverzeichnis.

Hinweise zu tmux

COLLIE_TMUX_BIN bleibt in der Regel ungesetzt. Collie prüft eine Liste von Standardpfaden und liest PATH nicht aus, da Hintergrunddienste und Herdr-Aktionen diese Variable nicht mit Login-Shells teilen.

Hinweis. Halten Sie Socket-Pfade kurz. Bei Unix-Domain-Sockets mit mehr als etwa 100 Zeichen schlägt die Verbindung fehl, und tmux gibt error connecting to … (File name too long) zurück. Verwenden Sie /run/user/<uid>/ oder /tmp statt eines tief verschachtelten Verzeichnispfads.

Bei tmux-Versionen vor 3.7 mit window-size auf manual führt das Erstellen eines Fensters zum Absturz des Servers. Collie blockiert die Fenstererstellung in diesem Zustand und weist Sie an, tmux set -g window-size latest auszuführen; Anforderungen listet die getesteten Versionen auf.

Hinweise zu zellij

Wenn Ihre Distribution keine zellij-Pakete enthält, laden Sie eine Binärdatei von GitHub-Releases von zellij herunter und platzieren Sie sie in Ihrem PATH.

Bleibt der Endpunkt leer, wird standardmäßig die einzelne laufende Sitzung verwendet. Wenn keine oder mehrere Sitzungen existieren, bricht Collie mit einem Fehler ab, anstatt eine auszuwählen. Wenn eine benannte Sitzung beendet wird, meldet Collie diese namentlich, anstatt zu einer aktiven zu wechseln.

Zellij benötigt XDG_RUNTIME_DIR, um Sitzungen zu finden. Wenn Collie alle Sitzungen als beendet meldet, prüfen Sie, ob der systemd-Dienst diese Umgebungsvariable enthält (Vertrag).

Zellij-Sitzungen bleiben unabhängig von ihrem ursprünglichen Terminal bestehen. Erstellen Sie eine Sitzung mit zellij -s collie-zellij und trennen Sie sie mit Ctrl o d. Auf Headless-Hosts startet zellij attach --create-background collie-zellij eine getrennte Sitzung direkt (getestet mit zellij 0.44.2).

Hinweis. Collie verwaltet aktive Sitzungen, erstellt oder startet sie jedoch nicht neu.

Hat es funktioniert?

collie doctor   # the `mux` check names the multiplexer, its endpoint,
                # and whether it answered

# `[bridge] mux: tmux · socket /run/user/1000/collie-tmux.sock`, printed at
# startup; a multiplexer it cannot reach is one warning line more
collie logs

# the herd, as the phone is given it
curl -s http://127.0.0.1:8787/api/snapshot | head -c 400

Dieser curl-Aufruf funktioniert ohne Authentifizierungs-Header. Leseanfragen umgehen die Gerätevalidierung, selbst wenn COLLIE_DEVICE_HEADER aktiviert ist (Konfiguration). Nur Schreibaktionen erfordern den konfigurierten Header.

Prüfen Sie die Smartphone-Benutzeroberfläche: Das Dashboard sollte Ihr tmux-Fenster oder zellij-Tabs anzeigen, und der Claude-Bereich sollte sich als Agent statt als bash identifizieren. Wenn Bereiche weiterhin als Standard-Shells angezeigt werden, überprüfen Sie die unten stehende Installation der Beacon-Hooks.

Collie schreibt Hooks in Claudes eigene Einstellungen

$ collie hooks install claude
$ collie hooks status
would install: /home/you/collie/bin/collie beacon emit  (this checkout)
/home/you/.claude/settings.json: installed (v1)

Da tmux und zellij Panes als generische Shells bereitstellen, müssen sich Agents selbst ankündigen. Dazu müssen die Beacon-Hooks von Collie in der Konfiguration von Claude Code installiert werden.

Die Ausgabe verweist auf den bin/collie-Pfad aus diesem Repository. Paketinstallationen verwenden den installierten Binärpfad (~/.local/bin/collie oder ~/.local/share/collie/current/bin/collie) anstelle von versionierten Verzeichnissen, damit Verknüpfungen über Aktualisierungen hinweg gültig bleiben.

Verhaltensdetails bei Konfigurationsänderungen von Claude:

• —
  Ändert die global ~/.claude/settings.json und alle aktiven CLAUDE_CONFIG_DIR. .claude/settings.json-Dateien auf Projektebene bleiben unberührt.
• —
  Fügt fünf-Hooks mit dem Tag # collie-beacon v1 und 10-Sekunden-Timeouts ein. Bestehende Hooks bleiben erhalten. hooks uninstall claude entfernt nur Collie-Einträge.
• —
  Laufende Claude-Prozesse laden die Konfiguration nicht neu. Starten Sie die Agents neu, um Änderungen zu übernehmen.
• —
  Nur Linux. Die Aktivitätsprüfung der Agents hängt von /proc ab. Andere Betriebssysteme senden keine Beacons.
• —
  Beacons sind multiplexerspezifisch. Sie erfassen Pane- und Sitzungsbezeichner für das aktive Backend. Ein Wechsel von COLLIE_MUX macht bestehende Beacons ungültig. Alte Beacons verbleiben auf der Festplatte, bis sie gelöscht werden, und sind unter dem beacons-Zähler von collie doctor sichtbar.
• —
  Wenn Sie COLLIE_STATE_DIR verwenden, exportieren Sie es in der Shell-Umgebung des Agents. collie beacon emit liest diese Variable direkt; andernfalls schreiben Beacons in das Standard-Statusverzeichnis, wo die Bridge sie nicht findet.

collie doctor enthält eine beacon-hooks-claude-Diagnoseprüfung, die auf fehlende Hooks oder fehlerhafte Pfade zu verschobenen Checkouts hinweist. Laufzeitdetails finden Sie unter Agent-Beacons.

Was sich im Vergleich zu Herdr ändert

Die nachstehende Tabelle fasst die wichtigsten Unterschiede zusammen. Die genaue Spezifikation finden Sie unter MUX_CONTRACT.md.

Ohne aktive Beacons stellen tmux und zellij Panes als einfache Shells dar, und der Pane-Verlauf wird als nicht verfügbar markiert, anstatt leeren Inhalt zurückzugeben.

Zwei Dinge, die sich auf dem Smartphone anders anfühlen

• —
  „vor Ns synchronisiert“: Dieser Indikator erscheint in der Dashboard-Kopfzeile, um das Datenalter anzuzeigen. Er wird nur wenn das Backend auf regelmäßiger Abfrage basiert angezeigt, wie etwa zellij (bis zu 12 s Abfrageintervall). Herdr und tmux übertragen Statusänderungen sofort, daher entfällt das Aktualitäts-Badge.
• —
  „Im Terminal anzeigen“: Diese Pane-Aktion fokussiert das ausgewählte Pane in Ihrem aktiven Host-Terminal. Sie ist deaktiviert unter zellij, da der Fokus-Befehl von zellij die Anweisung akzeptiert, ohne den Ansichtsstatus zu ändern.

Hinweis. Die mobile Oberfläche ändert den Fokus des Host-Terminals nie automatisch. Nur die explizite Aktion „Im Terminal anzeigen“ aktualisiert die Anzeige. Das Navigieren im Dashboard oder das Öffnen von Panes beeinflusst den aktiven Host-Cursor nicht (ADR 0031).

tmux-Tipps – Fenster nach einem Neustart wiederherstellen

Collie speichert keinen Multiplexer-Zustand. Ein Neustart eines tmux-Servers zerstört dessen Fenster und hinterlässt ein leeres Dashboard.

Sie können die Wiederherstellung des Zustands über Standard-tmux-Plugins verwalten: tpm für die Plugin-Verwaltung, tmux-resurrect zum Speichern von Sitzungsbäumen und tmux-continuum für automatisierte Snapshots.

Diese Werkzeuge stellen Fensterlayouts und Arbeitsverzeichnisse wieder her. Um den Konversationskontext wiederherzustellen, verwenden Sie die integrierten Flags von Claude: claude --resume oder claude --continue.

Hinweis. Laufende Agentenprozesse bleiben nicht erhalten. Starten Sie Claude Code nach der Wiederherstellung manuell neu.

zellij-Tipps – nach einem Neustart gibt es nichts wiederherzustellen

Zellij bietet kein Äquivalent zu tmux-resurrect. Sitzungen, die nach dem Trennen des Terminals fortbestehen, werden als (EXITED - attach to resurrect) angezeigt, und das Anhängen löst die erneute Ausführung von Sitzungsbefehlen aus.

Hinweis. Da das Anhängen Seiteneffekte erzeugt, hängt Collie Sitzungen weder an noch stellt es sie wieder her. Beendete Sitzungen erscheinen als nicht erreichbar, und die Benutzeroberfläche zeigt ein Trennungsbanner anstelle einer leeren Sitzungsliste an.

Starten Sie die Sitzung nach einem Neustart manuell (zellij -s collie-zellij oder zellij attach --create-background collie-zellij für Headless-Systeme) und starten Sie Agenten darin. Stellen Sie die Verbindung zu früheren Agenten-Sitzungen mit claude --resume oder claude --continue wieder her.

Agent-Beacons (optional, Linux)

Über ein Beacon identifiziert sich ein Agent gegenüber Collie unter tmux und zellij, wo ein Bereich sonst als generische Shell erscheint.

$ collie hooks install claude
$ collie hooks status
would install: /home/you/collie/bin/collie beacon emit  (this checkout)
/home/you/.claude/settings.json: installed (v1)

Ein Hook in den Einstellungen von Claude Code führt collie beacon emit aus. Dies schreibt eine Datei, die den Harness-Namen, die Sitzung und den Zielbereich enthält. Herdr verfolgt dies nativ. Details zur Einrichtung finden Sie in Collie auf einen Multiplexer ausrichten; dieser Abschnitt erklärt den Mechanismus.

Der obige Pfad verweist auf bin/collie aus dem lokalen Checkout. Eine Binärinstallation verweist auf ~/.local/bin/collie oder auf ~/.local/share/collie/current/bin/collie, wenn dieser Name nicht verknüpft ist, wie oben beschrieben. Der Befehl status führt keine Schreibvorgänge durch.

Das Ausführen von hooks uninstall claude entfernt nur von Collie hinzugefügte Einträge. Es ändert Ihre global-Claude-Konfiguration, keine Dateien auf Projektebene. Dies gilt nur für Linux: Die Aktivitätsprüfung prüft /proc, und Collie schreibt auf anderen Betriebssystemen keine Beacons.

Claude wird beim Start sofort sichtbar. Da der Hook bei SessionStart ausgelöst wird, wird ein offenes Pane, das auf Eingaben wartet, als untätiger Agent statt als Shell angezeigt.

Die Sichtbarkeit endet, wenn der Prozess beendet wird. Collie überprüft die sendende PID bei jeder Prüfung. Sobald der Agent terminiert, meldet sich der Bereich sofort als Standard-Shell, anstatt in einem unbekannten Zustand zu verharren.

Collie löscht dazu nicht die Beacon-Datei: Die Datei bleibt auf dem Datenträger, collie doctor meldet sie unter beacons als abgelaufen, und der nächste Hook-Aufruf überschreibt sie.

Dadurch kann das Dashboard Panes nach Agentenname statt nach bash benennen. Es ermöglicht "braucht Sie" sortiert Panes nach Blockierungsstatus und liefert den für Warnmeldungen erforderlichen Zustand. Der Pane-Verlauf stützt sich ebenfalls auf das Beacon, um den vom Journal verwendeten Sitzungsschlüssel bereitzustellen.

Hinweis. Beacons bieten keinen Steuerkanal. Ein Beacon bestimmt nur, was Collie anzeigt und abfragt. Es kann keinen Text senden, keine Tastenanschläge einfügen, keine Bereiche umbenennen, keine Sitzungen schließen und keine Zugriffskontrollen umgehen. Das Bedrohungsmodell und die ausgelassenen Felder sind in ADR 0024 dokumentiert.