これは [スクリプトと自動化](/docs/scripting) の 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 に制限されます。

関連する config key:

| 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\
' '{"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 に限定され
ることがあります。

## 関連

- [Scripting guide](/docs/scripting)
- [Conductor](/docs/conductor)
- [Configuration schema](/docs/configuration/schema)