Zum Inhalt springen
PaneflowPaneflow

Scripting-Referenz

CLI-Verben, Selektoren, JSON-RPC-Methoden, Event-Frames, Config-Keys, Workspace-Specs, Flow-Specs, MCP-Tools, Hooks und Exit-Codes für Paneflow-Automatisierung.

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.

VerbPrimäre Methode oder EngineSchreibt in Panes?Zweck
ls [--human]surface.listNeinListet Panes im aktiven Workspace
read <target>surface.readNeinLiest Pane-Scrollback
search <target> <pattern>surface.searchNeinDurchsucht Pane-Scrollback
ps [--json]fleet.listNeinListet erkannte Agenten über Workspaces hinweg
status <target> [--json]surface.statusNeinLiest Agent-Status eines Pane
new [--name] [--cwd] [--space]workspace.createNeinErstellt einen Workspace, im aktiven Space, sofern --space keinen anderen nennt
select <index>workspace.selectNeinWählt einen Workspace aus und wechselt zu seinem Space
split <h|v>surface.splitNeinTeilt ein Pane
focus <target>surface.focusNeinFokussiert ein Pane und seinen Workspace
send <target> <text>surface.send_textGatedBereitet Text vor oder submitted ihn
key <target> <keystroke>surface.send_keystrokeGatedSendet einen nicht submit-fähigen Tastendruck
wait --match <sel>surface.read, events.subscribeNeinBlockiert bis Pattern, Idle oder beides
watch [--surface <sel>] [--type <event>]events.subscribeNeinStreamt Lifecycle- und Surface-Events
up <file>Workspace-Spec-EngineNur VorbefüllungErstellt einen deklarativen Workspace
flow run <file>Flow-EngineGated für submit-fähige SchritteFührt einen lokalen Multi-Agent-DAG aus
sessions [--json] [--follow]Sitzungsstrom des WorkersNeinLiest 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

SelektorBeispielHinweise
Numerische idpaneflow read 42Matcht surface_id exakt
Namepaneflow status backendBester Selektor für langlebige Skripte
cmdline:<substr>paneflow read cmdline:viteVollständiges foreground argv unter Linux, ausführbarer Name unter macOS und Windows
cwd:<path>paneflow read cwd:/home/me/apiMatcht 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

CodeBedeutung
0Erfolg
1Runtime-Fehler: Instanz unerreichbar, Pane geschlossen, Gate verweigert oder Handler-Fehler
2CLI-Usage-Fehler
3Ziel nicht gefunden oder mehrdeutig, oder send hat einen Ziel-Agenten abgewiesen, der auf eine Entscheidung wartet oder den Vordergrund verlassen hat
4wait Timeout oder Flow-ready Timeout

Write-Gates

Lesen ist standardmäßig erlaubt. Schreiboperationen sind nach Capability getrennt:

OperationGate
send ohne --submitPANEFLOW_IPC_SCRIPTING=1 oder ai_unrestricted
send --submitPANEFLOW_IPC_SCRIPTING=1 oder ai_unrestricted
keyPANEFLOW_IPC_SCRIPTING=1
send --scope all, key --scope all, flow run --scope all aus einem Pane herausPANEFLOW_IPC_ORCHESTRATION=1
Host-session.input von einem Control-ClientPANEFLOW_IPC_SCRIPTING=1
Host-session.create von einem Control-Client mit Befehl, Prompt oder EnvPANEFLOW_IPC_ORCHESTRATION=1
Host-session.create von einem Control-Client, sonstPANEFLOW_IPC_SCRIPTING=1
Flow-Schritt mit submit = trueScripting-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:

KeyStandardBedeutung
ai_unrestrictedfalseErlaubt vertrauenswürdiger KI-Automatisierung, Text ohne Env-Gate zu submitten
ai_injection_fencetrueVerpackt surface.read Text in eine nicht vertrauenswürdige Terminal-Hülle
submit_paste_delay_ms70Basisverzögerung zwischen bracketed paste und submit carriage return
terminal.envnoneUmgebungsvariablen, die in neue Terminals injiziert werden

Read-Felder

paneflow read <target> --json und rohes surface.read geben zurück:

FeldBedeutung
textScrollback-Text, standardmäßig fenced
linesAnzahl zurückgegebener Zeilen
total_linesGesamtzahl vorgehaltener Zeilen
eofOb der Read die älteste vorgehaltene Zeile erreicht hat
output_generationMonotoner 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.

FeldBedeutung
pidAgent-Prozess-id, falls bekannt
toolAgent-Familie wie claude, codex, opencode oder gemini
statethinking, waiting_for_input, finished, errored, stalled, idle oder unknown_running
hookedOb der aktuelle Start über Lifecycle-Hooks berichtet, die Paneflow installiert; ein Hook aus einem früheren Start zählt nie
state_seqZähler pro Sitzung, der bei jedem Zustandsübergang steigt, bei status
reasonErkennungsgrund, einschließlich no_hook
surface_idPane-id
surface_namePane-Name
workspaceWorkspace-Index
active_tool_nameTool, das gerade im Agenten läuft
messageWartender Prompt oder Permission-Text
last_resultZusammenfassung des letzten Turns, wenn verfügbar
waiting_msZeit im Warten auf Eingabe
idle_msZeit seit beobachteter Aktivität
output_generationPane-Ausgabezähler bei status; fehlt, wenn unbekannt

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 FeldTypStandardHinweise
namestring"Workspace"Workspace-Titel
spacestringaktiver SpaceSpace-Name (beliebige Schreibweise) oder id; Default steht für den Standard-Space
layoutstring"even_h"even_h, even_v, main_vertical oder tiled
port_baseinteger3000Basis für ${port_offset} Allocation
[[panes]]arrayerforderlichEin Eintrag pro Pane
Pane-FeldTypStandardHinweise
cwdstringnoneMuss nach Expansion und Canonicalization existieren
agentstringnoneAgent-Launcher-Name, gegenseitig exklusiv mit command
commandstringnoneRoher Command, gegenseitig exklusiv mit agent
promptstringnoneWird in ein Agent-Input vorbefüllt, niemals durch up submitted
focusboolfalseGibt diesem Pane initialen Fokus
envtablenoneWird über terminal.env gemergt, unterstützt ${port_offset}
namestringnoneStabiler Selektorname
worktreestringnoneBranch-Name für einen verwalteten Worktree unter der Wurzel worktrees.dir (siehe Konfigurationsschema)
fromstringHEADBranch oder Commit, von dem der Worktree-Branch ausgeht, wenn up ihn anlegt
copy_envbooltrueKopiert die Einträge der .worktreeinclude des Repositories in den Worktree, ohne diese Datei die obersten .env* und AGENTS.override.md
setupstringnoneCommand, der vor dem Start läuft
setup_timeout_secsinteger300Setup-Timeout
worktree_teardownstring"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.

FeldTypHinweise
idstringErforderliche, eindeutige Step-id
needsarrayDependencies; bei foreach wartet es auf alle Instanzen
foreacharrayFan-out, eine Instanz pro Item
paneinline tableSpawned ein Pane mit Workspace-Pane-Feldern
sendinline table{ target, text, submit? }, erfordert eine Dependency
readytable{ pattern, timeout_secs? }, Regex-Barriere
capturetable{ var, lines }, captured 1-500 Zeilen nach ready
submitboolSubmitted den Prompt eines gespawnten Pane, erfordert Scripting-Zugriff

Variablen:

VariableScope
${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

EigenschaftWert
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
FramingNewline-delimited JSON-RPC 2.0
Request-ModellEine Anfrage pro Verbindung, außer events.subscribe
Lokales VertrauenNur gleicher Benutzer; kein Network Listener, kein Token, kein TLS
BackpressureConnection Cap und begrenzte Event-Queues geben strukturierte Fehler oder dropped Frames zurück

Capabilities zur Laufzeit prüfen:

bash
printf '%s\n' '{"jsonrpc":"2.0","method":"system.capabilities","params":{},"id":1}' \
| nc -U "$PANEFLOW_SOCKET_PATH"

JSON-RPC-Methoden

MethodeParamsRückgabe oder Hinweise
system.ping-Liveness-Check
system.capabilities-{scripting, methods[]}
system.identify-{name, version, protocol}
workspace.list-Workspaces mit globalen Indizes, Titeln und space: {id, name} oder null für den Standard-Space
workspace.current-Angezeigter Workspace mit seinem space
workspace.createname?, cwd?, layout?, space?Erstellt einen Workspace; space ist ein Name (beliebige Schreibweise) oder eine id, ohne Angabe der aktive Space; ein unbekannter wird mit unknown space: <value> abgelehnt
workspace.selectindexWechselt den Workspace und, wenn dessen Space ausgeblendet ist, auch den Space
workspace.closeindexSchließt einen Workspace
workspace.upname, layout, panes[], space?Deklarativer Spawn für up und Flow-Roots; space wie bei workspace.create
workspace.restore_layoutlayoutWendet einen Layout-Baum an
surface.list-{surfaces:[{surface_id,name,title,cwd,cmd,workspace,space}]}
surface.readsurface_id, lines?, offset?, fenced?Scrollback und output_generation
surface.searchsurface_id, pattern, max_matches?Case-insensitive substring matches
surface.renamesurface_id, nameBenennt ein Pane um oder leert den Namen
surface.focussurface_idFokussiert Pane und Workspace
surface.statussurface_idAgent-Status für ein Pane
surface.send_textsurface_id, text, submit?, paste?Gated PTY-Textschreibzugriff
surface.send_keystrokesurface_id, keystrokeEnv-gated, nicht submit-fähiger Tastendruck
surface.splitdirection, surface_id?, cwd?, command?, prompt?, env?, name?, managed_worktree?Teilt ein Pane
tmux.compatteam, surface_id, argv, scope_session?tmux-Befehl aus einem Claude-Code-Team-Pane; team ist das Token, das Paneflow den Panes dieses Teams gegeben hat, und die Antwort ist {stdout, stderr, exit}
fleet.list-Read-only Flotten-Snapshot
events.subscribesurfaces?, types?Persistenter newline-delimited Event-Stream

Die ai.*-Lifecycle-Methoden werden auf dem App-Socket nicht mehr angenommen; Lifecycle-Events kommen 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-TypBedeutung
subscribedSubscription bestätigt
ai.session_startAgent-Session startet
ai.prompt_submitPrompt wird submitted
ai.tool_useAgent meldet Tool-Nutzung
ai.notificationAgent fragt nach Eingabe oder Permission
ai.stopAgent-Turn stoppt
ai.exitAgent-Prozess beendet sich
ai.session_endAgent-Session schließt
surface_changedPane output_generation ist fortgeschritten
heartbeatIdle Keepalive
droppedSubscriber 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 stdio MCP server über denselben Paneflow-Socket.

ToolParamsRückgabe
list_panes-Panes mit surface_id, name, title, cwd, cmd, workspace
read_panetarget, lines?, offset?Scrollback-Text
search_panetarget, pattern, max_matches?Trefferzeilen
write_panetarget, text, submit?approval_pending, bis ein Mensch das Paar erlaubt, danach das Zustellergebnis; mit submit auch started und state

write_pane ist das einzige schreibende Tool und schreibt erst, nachdem ein Mensch dieses Paar von Agent-Sitzungen in Paneflow erlaubt hat; die Automatisierungsanleitung beschreibt seine Kontrollen. Kein Tool sendet Tastendrücke, fokussiert oder teilt 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. Hooks liefern die Identität des Agenten und die Metadaten seiner Sitzung an ps, status, watch und paneflow sessions; der Turn-Status stammt aus OSC 7501.

BefehlWirkung
paneflow integrations listListet 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 setupInstalliert jede erkannte Runtime, die einen Installer hat
paneflow hooks uninstallEntfernt die Integrationen und den MCP-Eintrag paneflow
paneflow hooks statusGibt 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, werden über ihren Prozess erkannt und erhalten nur dann einen Turn-Status, wenn sie ihn über OSC 7501 melden.

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 den deklarierten OSC-7501-Status jeder Sitzung auf einen Zustand, baut diesen Zustand nach einem Neustart von der Festplatte wieder auf und fasst nie eine laufende Shell an. status, send --submit und wait --idle lesen den reduzierten Zustand aus dem Worker, ob ein Fenster offen ist oder nicht; paneflow sessions liest den Worker direkt.

BefehlWirkung
paneflow serve startStartet den Worker für dieses PANEFLOW_HOME oder übernimmt den bereits laufenden
paneflow serve statusGibt 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

Verwandte Seiten