スクリプトリファレンス

これは スクリプトと自動化 の compact reference です。人間の script や LLM が正確に引用できる public surface を 列挙します。

CLI verb

paneflow binary はこれらの verb を intercept し、GUI startup の前に終了します。未知の verb は app を暗黙に起動せず、usage code 2 で終了します。

CLI が受け付ける alias: list_panes は ls、read_pane は read、search_pane は search に map されます。

Selector

何にも match しない selector、または複数 pane に match する selector は code 3 で終了します。ただし send --broadcast、 wait --any、wait --all のように複数 match を明示的に受け付 ける command は例外です。

Exit code

Write gate

読み取りはデフォルトで許可されています。書き込みは capability ごとに分かれます。

send は --submit がない限り carriage return を追加しません。 key は enter、ctrl-m、ctrl-j のような submit する keystroke を拒否します。1 つの surface.send_text payload は 64 KiB に制限されます。

関連する config key:

Read field

paneflow read <target> --json と raw surface.read は次を返しま す。

default と limit: lines は default 200 で、1-4000 に clamp さ れます。offset は buffer の末尾から始まります。範囲外の offset は invalid-params error です。

JSON-RPC param fenced は default で ai_injection_fence を使 います。CLI flag --raw は fenced: false を渡します。

Agent state field

paneflow ps --json は {"agents":[...]} を返します。 paneflow status <target> --json は 1 つの status object を返し ます。

空の fleet は exit code 0 で {"agents":[]} です。tracked agent がない pane は error ではなく idle state を返します。

Workspace spec

paneflow up <file> は TOML workspace spec を読みます。

${port_offset} は env value 内でのみ置換されます。不明な key は error です。workspace creation は pane を作る前に path を検 証します。

Flow spec

paneflow flow run <file> は TOML flow spec を読み、現在の Paneflow instance に対して実行します。

Variables:

runner は実行前に、unknown key、missing dependency、dependency cycle、invalid regex、undefined capture、pane budget、missing timeout を検証します。Ctrl-C は orchestration loop を止めま す。作成済み pane は Paneflow に残ります。

JSON-RPC connection

runtime で capability を probe します。

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

JSON-RPC method

ai.* lifecycle method は app socket で受け付けられなくなりました。 agent status は paneflow-ai-hook reporter から届き、events.subscribe は 引き続き ai.* event を配信します。

structured failure は JSON-RPC error envelope を使います: -32602 invalid params、-32601 gated method、-32001 permission、 -32000 backpressure。一部の legacy validation error はまだ result 内の {"error":"..."} として返ります。client は両方 を failure として扱ってください。

Event

paneflow watch と raw events.subscribe は newline-delimited JSON を emit します。最初の frame は subscription ack です。

dropped frame の後は、paneflow ps --json または paneflow status <target> --json で resync します。

MCP bridge

paneflow-mcp は、同じ Paneflow socket 上の read-only stdio MCP server です。

typing、submitting、focusing、splitting panes のための tool はあ りません。返された terminal output は信頼できない data として fenced されます。

Lifecycle hook

paneflow-ai-hook は stdin から event JSON を読み、lifecycle event (ai.stop、ai.notification など) を 1 つローカル host に送り、0 で 終了します。停止した Paneflow instance が agent を壊さないためです。この hook surface が status、notification、ps、status、watch、 paneflow sessions を支えます。

hook はマシンごとに一度、CLI か Settings > Agents からインストールします。 Claude Code の hook は $CLAUDE_CONFIG_DIR/settings.json (デフォルト ~/.claude/settings.json)、Codex の hook は $CODEX_HOME/hooks.json (デフォルト ~/.codex/hooks.json) に入り、Paneflow の pane の外ではすぐに 終了します。その他の agent には installer がなく、動作はしますが state は process detection に限定されます。

Worker とセッション

agent state は home ごとの worker が保持し、paneflow serve run として起動 されます。worker は PANEFLOW_HOME ごとに 1 つ切り離されて動作し、hook event をセッションごとの 1 つの状態にまとめ、再起動時にはディスクから再構築し、 実行中のシェルには一切触れません。ウィンドウが動いていないと ps と status は hook state を見られず、send --submit もそれで確認できません。 paneflow sessions は worker を直接読みます。

関連

• Scripting guide
• Conductor
• Configuration schema