Dies ist die kompakte Referenz zu Scripting und Automatisierung. Sie benennt die öffentliche Oberfläche, die ein menschliches Skript oder ein LLM exakt zitieren kann.
CLI-Verben
Das paneflow Binary fängt diese Verben ab und beendet sich vor dem
GUI-Start. Unbekannte Verben beenden mit Usage-Code 2, statt die App
stillschweigend zu starten.
| Verb | Primäre Methode oder Engine | Schreibt in Panes? | Zweck |
|---|---|---|---|
ls [--human] | surface.list | Nein | Listet Panes im aktiven Workspace |
read <target> | surface.read | Nein | Liest Pane-Scrollback |
search <target> <pattern> | surface.search | Nein | Durchsucht Pane-Scrollback |
ps [--json] | fleet.list | Nein | Listet erkannte Agenten über Workspaces hinweg |
status <target> [--json] | surface.status | Nein | Liest Agent-Status eines Pane |
new | workspace.create | Nein | Erstellt einen Workspace |
select <index> | workspace.select | Nein | Wählt einen Workspace aus |
split <h|v> | surface.split | Nein | Teilt ein Pane |
focus <target> | surface.focus | Nein | Fokussiert ein Pane und seinen Workspace |
send <target> <text> | surface.send_text | Gated | Bereitet Text vor oder submitted ihn |
key <target> <keystroke> | surface.send_keystroke | Gated | Sendet einen nicht submit-fähigen Tastendruck |
wait --match <sel> | surface.read, events.subscribe | Nein | Blockiert bis Pattern, Idle oder beides |
watch [--surface <sel>] [--type <event>] | events.subscribe | Nein | Streamt Lifecycle- und Surface-Events |
up <file> | Workspace-Spec-Engine | Nur Vorbefüllung | Erstellt einen deklarativen Workspace |
flow run <file> | Flow-Engine | Gated für submit-fähige Schritte | Führt einen lokalen Multi-Agent-DAG aus |
sessions [--json] [--follow] | Sitzungsstrom des Workers | Nein | Liest den Sitzungsstatus der Agenten, mit oder ohne Fenster |
Akzeptierte CLI-Aliasse: list_panes mappt auf ls, read_pane auf
read und search_pane auf search.
Selektoren
| Selektor | Beispiel | Hinweise |
|---|---|---|
| Numerische id | paneflow read 42 | Matcht surface_id exakt |
| Name | paneflow status backend | Bester Selektor für langlebige Skripte |
cmdline:<substr> | paneflow read cmdline:vite | Vollständiges foreground argv unter Linux, ausführbarer Name unter macOS und Windows |
cwd:<path> | paneflow read cwd:/home/me/api | Matcht das Arbeitsverzeichnis des Pane |
Ein Selektor ohne Treffer oder mit mehreren Treffern beendet mit Code
3, außer bei Commands, die mehrere Matches ausdrücklich akzeptieren,
etwa send --broadcast, wait --any und wait --all.
Exit-Codes
| Code | Bedeutung |
|---|---|
0 | Erfolg |
1 | Runtime-Fehler: Instanz unerreichbar, Pane geschlossen, Gate verweigert oder Handler-Fehler |
2 | CLI-Usage-Fehler |
3 | Ziel nicht gefunden oder mehrdeutig |
4 | wait Timeout oder Flow-ready Timeout |
Write-Gates
Lesen ist standardmäßig erlaubt. Schreiboperationen sind nach Capability getrennt:
| Operation | Gate |
|---|---|
send ohne --submit | PANEFLOW_IPC_SCRIPTING=1 oder ai_unrestricted |
send --submit | PANEFLOW_IPC_SCRIPTING=1 oder ai_unrestricted |
key | PANEFLOW_IPC_SCRIPTING=1 |
Flow-Schritt mit submit = true | Scripting-Capability aus system.capabilities |
send fügt keinen carriage return an, außer --submit ist gesetzt.
key verweigert submit-fähige Tasten wie enter, ctrl-m und
ctrl-j. Ein einzelnes surface.send_text Payload ist auf 64 KiB
begrenzt.
Relevante Config-Keys:
| Key | Standard | Bedeutung |
|---|---|---|
ai_unrestricted | false | Erlaubt vertrauenswürdiger KI-Automatisierung, Text ohne Env-Gate zu submitten |
ai_injection_fence | true | Verpackt surface.read Text in eine nicht vertrauenswürdige Terminal-Hülle |
submit_paste_delay_ms | 70 | Basisverzögerung zwischen bracketed paste und submit carriage return |
terminal.env | none | Umgebungsvariablen, die in neue Terminals injiziert werden |
Read-Felder
paneflow read <target> --json und rohes surface.read geben zurück:
| Feld | Bedeutung |
|---|---|
text | Scrollback-Text, standardmäßig fenced |
lines | Anzahl zurückgegebener Zeilen |
total_lines | Gesamtzahl vorgehaltener Zeilen |
eof | Ob der Read die älteste vorgehaltene Zeile erreicht hat |
output_generation | Monotoner Zähler, der durch Pane-Ausgabe fortschreitet |
Defaults und Limits: lines ist standardmäßig 200 und wird auf
1-4000 begrenzt. offset startet vom Ende des Buffers. Ein
out-of-range Offset ist ein invalid-params Fehler.
Der JSON-RPC-Parameter fenced nutzt standardmäßig
ai_injection_fence. Das CLI-Flag --raw setzt fenced: false.
Agent-State-Felder
paneflow ps --json gibt {"agents":[...]} zurück. paneflow status <target> --json gibt ein Statusobjekt zurück.
| Feld | Bedeutung |
|---|---|
pid | Agent-Prozess-id, falls bekannt |
tool | Agent-Familie wie claude, codex, opencode oder gemini |
state | thinking, waiting_for_input, finished, errored, stalled, idle oder unknown_running |
hooked | Ob Lifecycle-Hook-Events verbunden sind |
reason | Erkennungsgrund, einschließlich no_hook |
surface_id | Pane-id |
surface_name | Pane-Name |
workspace | Workspace-Index |
active_tool_name | Tool, das gerade im Agenten läuft |
message | Wartender Prompt oder Permission-Text |
last_result | Zusammenfassung des letzten Turns, wenn verfügbar |
waiting_ms | Zeit im Warten auf Eingabe |
idle_ms | Zeit seit beobachteter Aktivität |
output_generation | Pane-Ausgabezähler bei status |
Eine leere Flotte ist {"agents":[]} mit Exit-Code 0. Ein Pane ohne
getrackten Agenten gibt idle state zurück, keinen Fehler.
Workspace-Spec
paneflow up <file> liest eine TOML Workspace-Spec.
| Top-level Feld | Typ | Standard | Hinweise |
|---|---|---|---|
name | string | "Workspace" | Workspace-Titel |
layout | string | "even_h" | even_h, even_v, main_vertical oder tiled |
port_base | integer | 3000 | Basis für ${port_offset} Allocation |
[[panes]] | array | erforderlich | Ein Eintrag pro Pane |
| Pane-Feld | Typ | Standard | Hinweise |
|---|---|---|---|
cwd | string | none | Muss nach Expansion und Canonicalization existieren |
agent | string | none | Agent-Launcher-Name, gegenseitig exklusiv mit command |
command | string | none | Roher Command, gegenseitig exklusiv mit agent |
prompt | string | none | Wird in ein Agent-Input vorbefüllt, niemals durch up submitted |
focus | bool | false | Gibt diesem Pane initialen Fokus |
env | table | none | Wird über terminal.env gemergt, unterstützt ${port_offset} |
name | string | none | Stabiler Selektorname |
worktree | string | none | Branch-Name für einen verwalteten Worktree unter der Wurzel worktrees.dir (siehe Konfigurationsschema) |
from | string | HEAD | Branch oder Commit, von dem der Worktree-Branch ausgeht, wenn up ihn anlegt |
copy_env | bool | true | Kopiert die Einträge der .worktreeinclude des Repositories in den Worktree, ohne diese Datei die obersten .env* und AGENTS.override.md |
setup | string | none | Command, der vor dem Start läuft |
setup_timeout_secs | integer | 300 | Setup-Timeout |
worktree_teardown | string | "auto" | auto entfernt saubere Worktrees beim Schließen, keep lässt sie liegen |
${port_offset} wird nur in env Werten ersetzt. Unbekannte Keys sind
Fehler. Workspace-Erstellung validiert Pfade, bevor Panes erstellt
werden.
Flow-Spec
paneflow flow run <file> liest eine TOML Flow-Spec und führt sie
gegen die aktuelle Paneflow-Instanz aus.
| Feld | Typ | Hinweise |
|---|---|---|
id | string | Erforderliche, eindeutige Step-id |
needs | array | Dependencies; bei foreach wartet es auf alle Instanzen |
foreach | array | Fan-out, eine Instanz pro Item |
pane | inline table | Spawned ein Pane mit Workspace-Pane-Feldern |
send | inline table | { target, text, submit? }, erfordert eine Dependency |
ready | table | { pattern, timeout_secs? }, Regex-Barriere |
capture | table | { var, lines }, captured 1-500 Zeilen nach ready |
submit | bool | Submitted den Prompt eines gespawnten Pane, erfordert Scripting-Zugriff |
Variablen:
| Variable | Scope |
|---|---|
${item} | foreach Steps: cwd, name, worktree, env, send.target, ready.pattern, Prompts und Texte |
${var} | Captured values in send.text und submit-fähigem pane.prompt |
${var.<item>} | Captures aus einer foreach Gruppe |
Der Runner validiert unbekannte Keys, fehlende Dependencies,
Dependency-Zyklen, ungültige Regexes, undefinierte Captures,
Pane-Budget und fehlende Timeouts vor der Ausführung. Ctrl-C stoppt
die Orchestrierungsschleife; erzeugte Panes bleiben in Paneflow.
JSON-RPC-Verbindung
| Eigenschaft | Wert |
|---|---|
| Linux endpoint | $XDG_RUNTIME_DIR/paneflow/paneflow.sock; wenn XDG_RUNTIME_DIR nicht gesetzt oder kein beschreibbares Verzeichnis ist, $TMPDIR, sonst ~/.cache/run |
| macOS endpoint | $TMPDIR/paneflow/paneflow.sock, sonst ~/Library/Caches/run; XDG_RUNTIME_DIR wird ignoriert |
| Windows endpoint | \\.\pipe\paneflow |
| Framing | Newline-delimited JSON-RPC 2.0 |
| Request-Modell | Eine Anfrage pro Verbindung, außer events.subscribe |
| Lokales Vertrauen | Nur gleicher Benutzer; kein Network Listener, kein Token, kein TLS |
| Backpressure | Connection Cap und begrenzte Event-Queues geben strukturierte Fehler oder dropped Frames zurück |
Capabilities zur Laufzeit prüfen:
printf '%s\n' '{"jsonrpc":"2.0","method":"system.capabilities","params":{},"id":1}' \
| nc -U "$PANEFLOW_SOCKET_PATH"JSON-RPC-Methoden
| Methode | Params | Rückgabe oder Hinweise |
|---|---|---|
system.ping | - | Liveness-Check |
system.capabilities | - | {scripting, methods[]} |
system.identify | - | {name, version, protocol} |
workspace.list | - | Workspaces mit Indexes und Titeln |
workspace.current | - | Aktiver Workspace |
workspace.create | name?, cwd?, layout? | Erstellt einen Workspace |
workspace.select | index | Wechselt Workspace |
workspace.close | index | Schließt einen Workspace |
workspace.up | name, layout, panes[] | Deklarativer Spawn für up und Flow-Roots |
workspace.restore_layout | layout | Wendet einen Layout-Baum an |
surface.list | - | {surfaces:[{surface_id,name,title,cwd,cmd,workspace}]} |
surface.read | surface_id, lines?, offset?, fenced? | Scrollback und output_generation |
surface.search | surface_id, pattern, max_matches? | Case-insensitive substring matches |
surface.rename | surface_id, name | Benennt ein Pane um oder leert den Namen |
surface.focus | surface_id | Fokussiert Pane und Workspace |
surface.status | surface_id | Agent-Status für ein Pane |
surface.send_text | surface_id, text, submit?, paste? | Gated PTY-Textschreibzugriff |
surface.send_keystroke | surface_id, keystroke | Env-gated, nicht submit-fähiger Tastendruck |
surface.split | direction, surface_id?, cwd?, command?, prompt?, env?, name?, managed_worktree? | Teilt ein Pane |
fleet.list | - | Read-only Flotten-Snapshot |
events.subscribe | surfaces?, types? | Persistenter newline-delimited Event-Stream |
Die ai.*-Lifecycle-Methoden werden auf dem App-Socket nicht mehr
angenommen; der Agent-Status kommt vom paneflow-ai-hook-Reporter, und
events.subscribe liefert weiterhin ai.*-Events.
Strukturierte Fehler nutzen JSON-RPC error Envelopes: -32602
invalid params, -32601 gated method, -32001 permission und
-32000 backpressure. Einige Legacy-Validierungsfehler kommen noch
als {"error":"..."} in result; Clients sollten beide Formen als
Fehler behandeln.
Events
paneflow watch und rohes events.subscribe emitten
newline-delimited JSON. Der erste Frame bestätigt die Subscription.
| Event-Typ | Bedeutung |
|---|---|
subscribed | Subscription bestätigt |
ai.session_start | Agent-Session startet |
ai.prompt_submit | Prompt wird submitted |
ai.tool_use | Agent meldet Tool-Nutzung |
ai.notification | Agent fragt nach Eingabe oder Permission |
ai.stop | Agent-Turn stoppt |
ai.exit | Agent-Prozess beendet sich |
ai.session_end | Agent-Session schließt |
surface_changed | Pane output_generation ist fortgeschritten |
heartbeat | Idle Keepalive |
dropped | Subscriber laggte und Events wurden verworfen |
Nach einem dropped Frame mit paneflow ps --json oder paneflow status <target> --json neu synchronisieren.
MCP-Bridge
paneflow-mcp ist ein read-only stdio MCP server über denselben
Paneflow-Socket.
| Tool | Params | Rückgabe |
|---|---|---|
list_panes | - | Panes mit surface_id, name, title, cwd, cmd, workspace |
read_pane | target, lines?, offset? | Scrollback-Text |
search_pane | target, pattern, max_matches? | Trefferzeilen |
Es gibt kein Tool zum Tippen, Submitten, Fokussieren oder Teilen von Panes. Zurückgegebene Terminalausgabe wird als nicht vertrauenswürdige Daten fenced.
Lifecycle-Hooks
paneflow-ai-hook liest Event-JSON von stdin, sendet ein Lifecycle-Event
(ai.stop, ai.notification usw.) an den lokalen Host und beendet mit 0,
damit eine gestoppte Paneflow-Instanz den Agenten nicht kaputtmacht. Die
Hook-Oberfläche treibt Status, Benachrichtigungen, ps, status, watch und
paneflow sessions.
| Befehl | Wirkung |
|---|---|
paneflow integrations list | Listet die Runtimes mit Installer und ihren Zustand |
paneflow integrations install <runtime> | Installiert die Hooks für claude-code (oder claude) oder codex und registriert den MCP-Server paneflow |
paneflow integrations remove <runtime> | Entfernt nur Paneflows eigene Handler; ein eigener Handler in derselben Hook-Gruppe bleibt erhalten |
paneflow hooks setup | Installiert jede erkannte Runtime, die einen Installer hat |
paneflow hooks uninstall | Entfernt die Integrationen und den MCP-Eintrag paneflow |
paneflow hooks status | Gibt eine Zeile <runtime>: <state> pro Runtime aus; beendet immer mit 0 |
Hooks werden einmal pro Rechner installiert, über die CLI oder
Settings > Agents. Claude-Code-Hooks landen in
$CLAUDE_CONFIG_DIR/settings.json (Standard ~/.claude/settings.json),
Codex-Hooks in $CODEX_HOME/hooks.json (Standard ~/.codex/hooks.json), und
außerhalb einer Paneflow-Pane beenden sie sich sofort. Andere Agenten haben
keinen Installer: Sie laufen weiter, aber ihr Status ist auf Prozesserkennung
begrenzt.
Worker und Sitzungen
Der Agentenstatus lebt in einem Worker pro Home, gestartet als
paneflow serve run. Er läuft abgekoppelt, einer pro PANEFLOW_HOME,
reduziert Hook-Events auf einen Zustand pro Sitzung, baut diesen Zustand nach
einem Neustart von der Festplatte wieder auf und fasst nie eine laufende Shell
an. Ohne laufendes Fenster sehen ps und status keinen Hook-Status, und
send --submit kann darüber nicht bestätigen; paneflow sessions liest den
Worker direkt.
| Befehl | Wirkung |
|---|---|
paneflow serve start | Startet den Worker für dieses PANEFLOW_HOME oder übernimmt den bereits laufenden |
paneflow serve status | Gibt PID, Protokoll, Home, Anzahl der Sitzungen und Fähigkeiten aus |
paneflow serve stop [--drain-ms 5000] | Stoppt den Worker; Terminals bleiben unberührt |
paneflow sessions [--json] [--follow] | Gibt die Sitzungsliste der Seitenleiste aus; --follow gibt eine Zeile pro Übergang aus und verbindet sich neu, wenn der Worker neu startet |
paneflow sessions ack <session-id>... | Senkt das Flag unread, das ein beendeter Turn setzt |