Scripting und Automatisierung

Paneflow stellt eine begrenzte lokale Automatisierungsoberfläche bereit. Das Binary paneflow kann als CLI-Client laufen, mit der laufenden GUI über einen lokalen JSON-RPC-Socket sprechen und vor dem Start von GPUI wieder beenden.

Nutze es, um Panes zu inspizieren, Scrollback zu lesen, Agent-Events zu streamen, Prompts vorzubereiten, Workspaces zu erstellen oder einen Multi-Agent-Flow auszuführen. Die Grenze ist absichtlich gesetzt: Leseoperationen funktionieren standardmäßig, Schreiben in ein PTY ist explizit geschützt.

Für exakte Verben, Methodenfelder, Event-Namen und Exit-Codes halte die Scripting-Referenz neben diesem Guide offen.

Welche Schnittstelle sollte ich verwenden?

CLI und MCP-Bridge nutzen denselben lokalen Socket. In einem Paneflow Pane wird PANEFLOW_SOCKET_PATH automatisch injiziert. Außerhalb von Paneflow kannst du die Variable setzen, falls die Socket-Erkennung die laufende Instanz nicht findet.

Wie inspiziere ich Panes und Agenten?

Nutze ps für die Agentenflotte, ls für Panes im aktiven Workspace, status für ein einzelnes Pane und read oder search für Terminalausgabe.

paneflow ps --json
paneflow ls --human
paneflow status backend --json
paneflow read backend --lines 120
paneflow search backend "test result" --max 5

status und read --json enthalten output_generation, einen monotonen Zähler, der steigt, wenn sich die Pane-Ausgabe ändert. Agenten können damit erkennen, ob ein Pane ruhig geworden ist, ohne zu raten.

Für Push statt Polling nutze watch:

paneflow watch
paneflow watch --surface backend --type ai.stop
paneflow watch --type ai.notification --type surface_changed

watch streamt newline-delimited JSON aus events.subscribe, bis du es stoppst.

Wie schreibe ich sicher?

send bereitet Text in einem Pane vor. Es drückt nicht Enter, außer du setzt --submit.

paneflow send reviewer "Review the current diff and report the top risks."
paneflow send reviewer "Run the focused tests and report failures only." --submit
paneflow send reviewer "Write the final report to the provided file." --report-file /tmp/paneflow-review.md --submit
paneflow key backend ctrl-c

Schreiben ist geschützt, weil jeder Prozess mit derselben UID, der in ein PTY schreiben kann, einen Agenten oder eine Shell steuern kann. Es gibt zwei relevante Kontrollen:

Lass ai_injection_fence aktiviert. Ein peer Pane kann feindlichen Terminaltext enthalten, besonders wenn es einen Agenten über einem nicht vertrauenswürdigen Repo ausführt. Die Fence hilft einem LLM, diese Ausgabe als Evidenz zu behandeln, nicht als Anweisung.

Nutze --raw nur für vertrauenswürdige menschliche Skripte. Nutze --report-file, wenn ein Vollbild-Agent Scrollback überschreiben oder abschneiden kann. Nutze --paste nur, wenn du bracketed-paste erzwingen musst; Paneflow erkennt für bekannte Agent-Panes bereits automatisch den sichereren Paste-Pfad.

Wie erstelle ich einen Workspace aus TOML?

paneflow up <file> erstellt einen Workspace mit Panes, Arbeitsverzeichnissen, Agent-Befehlen, vorbefüllten Prompts, Umgebungsvariablen und optionalen Worktrees.

# paneflow.workspace.toml
name = "feat-x"
layout = "main_vertical"

[[panes]]
cwd = "~/dev/api"
agent = "claude"
prompt = "review the diff on this branch"
name = "reviewer"
focus = true

[[panes]]
cwd = "~/dev/api"
command = "cargo watch -x test"
name = "tests"

Führe paneflow up paneflow.workspace.toml --dry-run aus, um den aufgelösten Plan zu validieren, ohne die laufende Instanz zu ändern. Prompts werden vorbefüllt, nicht submitted.

Wie führe ich einen Multi-Agent-Flow aus?

Nutze paneflow flow run <file>, wenn der Workflow Abhängigkeiten, Barrieren, Capture, Fan-out oder einen finalen maschinenlesbaren Report braucht.

# flow.toml
name = "review-pipeline"
layout = "even_h"

[defaults]
timeout_secs = 600

[[step]]
id = "impl"
pane = { cwd = "~/dev/api", agent = "claude", prompt = "implement the fix and run tests" }
submit = true
ready = { pattern = "tests? passed" }
capture = { var = "summary", lines = 20 }

[[step]]
id = "review"
needs = ["impl"]
send = { target = "impl", text = "Summarise what changed:\n${summary}" }

Jeder Schritt, der submitted, erfordert das Write-Gate. Ein Flow mit Submit prüft die Fähigkeiten vorab, auch unter --dry-run, und scheitert dadurch, bevor Teilzustand erzeugt wird.

Wie passt MCP hinein?

paneflow-mcp ist read-only. Es stellt unterstützten Agenten list_panes, read_pane und search_pane bereit. Es kann nicht tippen, Prompts submitten, Tastendrücke senden oder ein anderes Pane steuern.

paneflow mcp install
paneflow mcp status
paneflow mcp uninstall

Die Installation deckt Claude Code, Codex, Gemini CLI und opencode Configs ab, ohne fremde Einträge zu überschreiben.

Wie passen Lifecycle-Hooks hinein?

Lifecycle-Hooks melden den Agent-Status an Paneflow zurück. Sie treiben Sidebar-Status, Benachrichtigungen, ps, status und watch; sie sind kein generisches Workflow-Trigger-System.

paneflow hooks setup
paneflow hooks status
paneflow hooks uninstall

Persistentes Setup ist auf Claude Code beschränkt. Codex erhält Hooks pro Start über den Shim. Agenten ohne Hook-Oberfläche können weiterhin in Panes laufen, aber Flottenstatus und Lifecycle-Events sind eingeschränkt.

Verwandte Seiten

• Scripting-Referenz für die exakte Command-, RPC-, Event- und Config-Oberfläche.
• Conductor für den agentenorientierten Workflow auf diesen Primitiven.
• Konfigurationsschema für paneflow.json-Keys.