Diese Seite ist die kompakte Referenz für Conductor. Sie benennt die öffentliche Oberfläche und die Felder, auf die sich ein Skript oder LLM verlassen kann.
CLI-Verben
| Verb | Primäre Methode | Nutzung |
|---|---|---|
ps [--json] | fleet.list | Erkannte Agents über Workspaces listen |
status <target> [--json] | surface.status | Agent-Status einer Pane lesen |
watch [--surface <sel>] [--type <event>] | events.subscribe | Lifecycle-Events und Surface-Änderungen streamen |
read <target> | surface.read | Pane-Scrollback lesen |
send <target> <text> | surface.send_text | Text in einer Pane vorbereiten oder absenden |
wait --match <sel> | surface.read, Eventstream im Idle-Modus | Bis Idle-State, Regex oder beidem blockieren |
up <file> | Workspace-Orchestrierung | Deklarativen Agent-Workspace erstellen |
flow run <file> | Flow-Orchestrierung | Multi-Agent-Pipeline starten |
ls, search, focus, key | Scripting-Methoden | Niedrigere Pane-Automation nutzen |
Leseoperationen sind standardmäßig erlaubt. Schreiboperationen wie send --submit, key und Flow-Schritte, die Text absenden, brauchen den Scripting-Gate oder AI free access.
Selektoren
| Selektor | Beispiel | Hinweise |
|---|---|---|
| Numerische id | paneflow status 42 | Exakte Pane-Id |
| Name | paneflow status backend | Bester Selektor für Conductor-Workflows |
cmdline:<substr> | paneflow read cmdline:claude | Nützlich, aber weniger portabel als ein Pane-Name |
cwd:<path> | paneflow read cwd:/home/me/app | Gut für repo-bezogene Skripte |
Ein Selektor, der nichts oder mehrere Panes trifft, beendet mit Code 3, außer Befehle erlauben mehrere Treffer ausdrücklich, etwa Broadcast-Sends oder wait --any und wait --all.
fleet.list
paneflow ps --json gibt ein agents Array zurück.
| Feld | Bedeutung |
|---|---|
pid | Agent-Prozess-ID, oder null für scan-only Erkennung |
tool | Agent-Familie wie claude, codex, opencode oder gemini |
state | thinking, waiting_for_input, finished, errored, stalled, idle oder unknown_running |
hooked | true, wenn Paneflow Lifecycle-Hook-Events empfängt |
reason | Erkennungsgrund, inklusive no_hook für nicht gehookte Prozesse |
surface_id | Pane-Id, wenn aufgelöst |
surface_name | Pane-Name, wenn vorhanden |
workspace | Workspace-Index |
active_tool_name | Aktuell laufendes Tool im Agent, wenn gemeldet |
message | Wartende Frage oder Permission-Text, wenn gemeldet |
last_result | Zusammenfassung des letzten Turns, wenn der Hook sie liefert |
waiting_ms | Millisekunden in Wartezustand |
idle_ms | Millisekunden seit der letzten beobachteten Aktivität |
Eine leere Flotte ist {"agents":[]} mit Exit-Code 0.
surface.status
paneflow status <target> --json gibt einen Pane-Status zurück.
| Feld | Bedeutung |
|---|---|
surface_id | Pane-Id |
state | Dieselbe State-Vokabel wie fleet.list |
hooked | Ob Lifecycle-Tracking aktiv ist |
tool | Agent-Familie, wenn erkannt |
active_tool_name | Aktuell laufendes Tool, wenn gemeldet |
message | Wartende Frage oder Permission-Text, wenn gemeldet |
last_result | Zusammenfassung des letzten Turns, wenn verfügbar |
waiting_ms | Millisekunden in Wartezustand |
idle_ms | Millisekunden seit der letzten beobachteten Aktivität |
output_generation | Monotoner Zähler, der bei Pane-Ausgabe fortschreitet |
Eine Pane ohne aktiven Agent gibt einen Idle-State statt eines Fehlers zurück.
surface.read
paneflow read <target> gibt Terminaltext zurück. Standardmäßig wird Ausgabe in <untrusted_terminal_output> verpackt, damit ein LLM sie lesen kann, ohne sie als Anweisung zu behandeln. Nutzen Sie --raw nur für vertrauenswürdige Mensch-Skripte.
Nützliche Felder im JSON-Modus sind text, lines, total_lines, eof und output_generation.
events.subscribe und watch
paneflow watch ist newline-delimited JSON. Es kann ausgeben:
| Event-Typ | Bedeutung |
|---|---|
ai.session_start | Eine Agent-Session beginnt |
ai.prompt_submit | Ein Prompt wird gesendet |
ai.tool_use | Der Agent ruft ein Tool auf |
ai.notification | Der Agent stellt eine Frage oder fordert Permission an |
ai.stop | Ein Turn endet |
ai.exit | Der Agent-Prozess beendet sich |
ai.session_end | Die Session schließt |
surface_changed | output_generation der Pane ist fortgeschritten |
Kontrollframes sind ebenfalls gültig:
| Frame | Bedeutung |
|---|---|
subscribed | Subscription bestätigt |
heartbeat | Keepalive-Frame |
dropped | Der Subscriber lag zurück und Events wurden verworfen |
Wenn ein Client dropped erhält, sollte er mit paneflow ps --json oder paneflow status <target> --json resynchronisieren.
wait
wait --idle nutzt den Eventstream, wenn er verfügbar ist, und fällt bei Bedarf sicher zurück. wait --pattern pollt aktuellen Scrollback alle 500 ms und scannt die letzten 500 Zeilen.
| Modus | Beispiel | Nutzung |
|---|---|---|
| Idle | paneflow wait --match reviewer --idle --timeout 600 | Nach Ende der Agent-Arbeit fortfahren |
| Pattern | paneflow wait --match backend --pattern '^DONE:' --timeout 300 | Nach einer Sentinel-Zeile fortfahren |
| Idle plus pattern | paneflow wait --match reviewer --idle --pattern '^REPORT_DONE' --timeout 600 | Stabile Pane und Marker verlangen |
| Any oder all | paneflow wait --match 'cmdline:claude' --pattern 'tests passed' --all | Mehrere Panes im Pattern-Modus koordinieren |
Timeouts enden mit Code 4.
Konfigurationsschlüssel
| Schlüssel | Standard | Bedeutung |
|---|---|---|
ai_unrestricted | false | Erlaubt vertrauenswürdiger KI-Automation das Absenden, wenn aktiv |
ai_injection_fence | true | Verpackt Peer-Terminalausgabe als nicht vertrauenswürdigen Text |
agent_stall_threshold_secs | App-Default | Markiert stille laufende Turns als stalled |
Exit-Codes
| Code | Bedeutung |
|---|---|
0 | Erfolg |
1 | Runtime-Fehler |
2 | CLI-Nutzungsfehler |
3 | Ziel nicht gefunden oder mehrdeutig |
4 | wait Timeout |