スクリプトリファレンス

Paneflow 自動化の CLI verb、selector、JSON-RPC method、event frame、config key、workspace spec、flow spec、MCP tool、hook、exit code。

2026年7月1日に更新

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

CLI verb

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

Verb	主な method または engine	pane に書き込むか	用途
`ls [--human]`	`surface.list`	いいえ	active workspace の pane を一覧
`read <target>`	`surface.read`	いいえ	pane scrollback を読む
`search <target> <pattern>`	`surface.search`	いいえ	pane scrollback を検索
`ps [--json]`	`fleet.list`	いいえ	workspace 全体の検出済み agent を一覧
`status <target> [--json]`	`surface.status`	いいえ	1 つの pane の agent state を読む
`new`	`workspace.create`	いいえ	workspace を作成
`select <index>`	`workspace.select`	いいえ	workspace を選択
`split <h\|v>`	`surface.split`	いいえ	pane を split
`focus <target>`	`surface.focus`	いいえ	pane とその workspace を focus
`send <target> <text>`	`surface.send_text`	gated	text を stage または submit
`key <target> <keystroke>`	`surface.send_keystroke`	gated	submit しない keystroke を送信
`wait --match <sel>`	`surface.read`, `events.subscribe`	いいえ	pattern、idle、または両方まで block
`watch [--surface <sel>] [--type <event>]`	`events.subscribe`	いいえ	lifecycle event と surface event を stream
`up <file>`	Workspace spec engine	prefill のみ	宣言的 workspace を作成
`flow run <file>`	Flow engine	submit する step は gated	ローカル multi-agent DAG を実行

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

Selector

Selector	例	Notes
Numeric id	`paneflow read 42`	`surface_id` と完全一致
Name	`paneflow status backend`	長く使う script で最も安定
`cmdline:<substr>`	`paneflow read cmdline:vite`	Linux では full foreground argv、macOS と Windows では executable basename
`cwd:<path>`	`paneflow read cwd:/home/me/api`	pane working directory と一致

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

Exit code

Code	Meaning
`0`	成功
`1`	Runtime failure: instance unreachable、pane closed、gate refused、handler error
`2`	CLI usage error
`3`	target not found または ambiguous
`4`	`wait` timeout または flow ready timeout

Write gate

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

Operation	Gate
`send` without `--submit`	`PANEFLOW_IPC_SCRIPTING=1` または `ai_unrestricted`
`send --submit`	`PANEFLOW_IPC_SCRIPTING=1` または `ai_unrestricted`
`key`	`PANEFLOW_IPC_SCRIPTING=1`
`submit = true` の flow step	`system.capabilities` が report する scripting capability

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

Key	Default	Meaning
`ai_unrestricted`	`false`	信頼された AI automation が env gate なしで text を submit できる
`ai_injection_fence`	`true`	`surface.read` text を信頼できない terminal envelope で包む
`submit_paste_delay_ms`	`70`	bracketed paste と submit carriage return の間の base delay
`terminal.env`	none	新しい terminal に注入される environment variable

Read field

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

Field	Meaning
`text`	scrollback text。デフォルトで fenced
`lines`	返された line count
`total_lines`	保持されている total line count
`eof`	read が保持されている最古の line に到達したか
`output_generation`	pane output によって進む monotonic counter

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 を返します。

Field	Meaning
`pid`	agent process id。既知の場合
`tool`	`claude`、`codex`、`opencode`、`gemini` などの agent family
`state`	`thinking`、`waiting_for_input`、`finished`、`errored`、`stalled`、`idle`、`unknown_running`
`hooked`	lifecycle hook event が attached されているか
`reason`	detection reason。`no_hook` を含む
`surface_id`	pane id
`surface_name`	pane name
`workspace`	workspace index
`active_tool_name`	agent 内で現在動作している tool
`message`	waiting prompt または permission text
`last_result`	利用可能な場合の last turn summary
`waiting_ms`	input 待ちに費やした時間
`idle_ms`	最後に観測された activity からの時間
`output_generation`	`status` 上の pane output counter

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

Workspace spec

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

Top-level field	Type	Default	Notes
`name`	string	`"Workspace"`	workspace title
`layout`	string	`"even_h"`	`even_h`、`even_v`、`main_vertical`、`tiled`
`port_base`	integer	`3000`	`${port_offset}` allocation の base
`[[panes]]`	array	required	pane ごとに 1 entry

Pane field	Type	Default	Notes
`cwd`	string	none	expansion と canonicalization 後に存在する必要がある
`agent`	string	none	agent launcher name。`command` と mutually exclusive
`command`	string	none	raw command。`agent` と mutually exclusive
`prompt`	string	none	agent input に prefill される。`up` は submit しない
`focus`	bool	`false`	この pane に initial focus を与える
`env`	table	none	`terminal.env` の上に merge。`${port_offset}` を support
`name`	string	none	stable selector name
`worktree`	string	none	`<repo>.worktrees/` 配下の managed worktree 用 branch name
`copy_env`	bool	`true`	gitignored `.env*` files を worktree に copy
`setup`	string	none	launch 前に実行される command
`setup_timeout_secs`	integer	`300`	setup timeout
`worktree_teardown`	string	`"auto"`	`auto` は close 時に clean worktree を削除、`keep` は残す

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

Flow spec

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

Field	Type	Notes
`id`	string	required。unique step id
`needs`	array	dependency。`foreach` では全 instance を待つ
`foreach`	array	fan-out。item ごとに 1 instance
`pane`	inline table	workspace pane field を使って pane を spawn
`send`	inline table	`{ target, text, submit? }`。dependency が必要
`ready`	table	`{ pattern, timeout_secs? }`。regex barrier
`capture`	table	`{ var, lines }`。`ready` 後に 1-500 lines を capture
`submit`	bool	spawned pane prompt を submit。scripting access が必要

Variables:

Variable	Scope
`${item}`	`foreach` step: `cwd`、`name`、`worktree`、`env`、`send.target`、`ready.pattern`、prompt、text
`${var}`	`send.text` と submitting `pane.prompt` 内の captured value
`${var.<item>}`	`foreach` group からの capture

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

JSON-RPC connection

Property	Value
Linux endpoint	`$XDG_RUNTIME_DIR/paneflow/paneflow.sock`
macOS endpoint	user runtime dir。同じ Paneflow socket name
Windows endpoint	`\\.\pipe\paneflow`
Framing	Newline-delimited JSON-RPC 2.0
Request model	`events.subscribe` 以外は 1 connection につき 1 request
Local trust	same user only。network listener、token、TLS はなし
Backpressure	connection cap と bounded event queue が structured error または `dropped` frame を返す

runtime で capability を probe します。

bash

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

JSON-RPC method

Method	Params	Returns or notes
`system.ping`	-	liveness check
`system.capabilities`	-	`{scripting, methods[]}`
`system.identify`	-	`{name, version, protocol}`
`workspace.list`	-	index と title を持つ workspace
`workspace.current`	-	active workspace
`workspace.create`	`name?`, `cwd?`, `layout?`	workspace を作成
`workspace.select`	`index`	workspace を切り替え
`workspace.close`	`index?`	workspace を閉じる
`workspace.up`	`name`, `layout`, `panes[]`	`up` と flow root が使う declarative spawn
`workspace.restore_layout`	`layout`	layout tree を適用
`surface.list`	-	`{surfaces:[{surface_id,name,title,cwd,cmd,workspace}]}`
`surface.read`	`surface_id`, `lines?`, `offset?`, `fenced?`	scrollback と `output_generation`
`surface.search`	`surface_id`, `pattern`, `max_matches?`	case-insensitive substring match
`surface.rename`	`surface_id`, `name`	pane name を rename または clear
`surface.focus`	`surface_id`	pane と workspace を focus
`surface.status`	`surface_id`	1 つの pane の agent state
`surface.send_text`	`surface_id`, `text`, `submit?`, `paste?`	gated PTY text write
`surface.send_keystroke`	`surface_id`, `keystroke`	env-gated non-submitting keystroke
`surface.split`	`direction`, `surface_id?`, `cwd?`, `command?`, `prompt?`, `env?`, `name?`, `managed_worktree?`	pane を split
`fleet.list`	-	read-only fleet snapshot
`events.subscribe`	`surfaces?`, `types?`	persistent newline-delimited event stream
`ai.session_start`	hook payload	lifecycle telemetry
`ai.prompt_submit`	hook payload	lifecycle telemetry
`ai.tool_use`	hook payload	lifecycle telemetry
`ai.notification`	hook payload	lifecycle telemetry
`ai.stop`	hook payload	lifecycle telemetry
`ai.exit`	hook payload	lifecycle telemetry
`ai.session_end`	hook payload	lifecycle telemetry

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 です。

Event type	Meaning
`subscribed`	subscription acknowledged
`ai.session_start`	agent session starts
`ai.prompt_submit`	prompt is submitted
`ai.tool_use`	agent reports tool use
`ai.notification`	agent asks for input or permission
`ai.stop`	agent turn stops
`ai.exit`	agent process exits
`ai.session_end`	agent session closes
`surface_changed`	pane `output_generation` advanced
`heartbeat`	idle keepalive
`dropped`	subscriber lagged and events were shed

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

MCP bridge

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

Tool	Params	Returns
`list_panes`	-	`surface_id`、`name`、`title`、`cwd`、`cmd`、`workspace` を持つ pane
`read_pane`	`target`, `lines?`, `offset?`	scrollback text
`search_pane`	`target`, `pattern`, `max_matches?`	matching lines

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

Lifecycle hook

paneflow-ai-hook は stdin から event JSON を読み、JSON-RPC ai.* frame を 1 つ post し、0 で終了します。停止した Paneflow instance が agent を壊さないためです。この hook surface が status、notification、ps、status、watch を支えます。

persistent paneflow hooks setup は Claude Code scoped です。 Codex は launch ごとの shim hook を使います。hook surface のない agent も動きますが、state は process detection に限定されることがあります。