paneflow.json 模式参考

paneflow.json 的每个键、类型、默认值、应用时机和 runtime notes。

最后更新于 2026年7月21日

paneflow.json 是按用户存储的 JSON 文件。所有键都是可选的，{} 也是有效配置。实际行为以 Rust config loader 和 runtime resolver 为准；发布的 JSON Schema 用于向编辑器暴露公共键、验证和自动补全。

未知的 top-level key 会在 runtime 被忽略，但编辑器会通过 schema 标记出来。有效保存会被 config watcher 重新加载。Hot reload 时，如果 JSON 无效，Paneflow 会保留上一份有效配置，而不是广播 defaults。启动时遇到无效文件会回退到 defaults 并写入 warning 日志。

File locations

Platform	Path
Linux	`~/.config/paneflow/paneflow.json`
macOS	`~/Library/Application Support/paneflow/paneflow.json`
Windows	`%APPDATA%\paneflow\paneflow.json`

Editor schema

Add this at the top of the file for autocomplete in VS Code, Zed, JetBrains IDEs, Helix, and other JSON Schema-aware editors:

paneflow.json

{
"$schema": "https://github.com/arthjean/paneflow/raw/main/schemas/paneflow.schema.json",
"$schemaVersion": "1.0.0"
}

Top-level keys

Key	Type	Default	Applied	Notes
`$schema`	string	none	Editor only	Points editors to the published schema. Ignored by Paneflow.
`$schemaVersion`	string	`1.0.0`	Startup/reload	Unknown versions warn but do not block loading.
`default_shell`	string/null	Platform shell fallback	New terminal	Falls back through configured executable, `$SHELL`, `/bin/sh`, then `%COMSPEC%` on Windows.
`theme`	string/null	`One Dark`	Hot reload	Built-ins: `One Dark`, `PaneFlow Light`. Runtime lookup is case-insensitive.
`theme_mode`	string/null	`dark`	Hot reload	`light` and `dark` force the matching bundled theme; `system` follows the OS window appearance.
`font_family`	string/null	`JetBrainsMono NFM` if installed, else `Lilex`	Hot reload cache	Accepts `.PaneflowMono`, `.PaneflowSans`, embedded font names, or installed monospace families.
`font_fallbacks`	string array/null	GPUI fallback stack	Hot reload cache	Ordered extra fallback families for glyphs missing from `font_family`.
`font_size`	number/null	`13.0`	Hot reload cache	Points, valid range `8.0` to `32.0`; invalid values fall back to `13.0`.
`font_weight`	string/null	`normal`	Hot reload cache	One of `thin`, `extra_light`, `light`, `semi_light`, `normal`, `medium`, `semi_bold`, `bold`, `extra_bold`, `black`, `extra_black`.
`line_height`	number/null	`1.2`	Hot reload cache	Multiplier, valid range `1.0` to `2.5`; invalid values fall back to `1.2`.
`cell_width`	number/null	`0.6`	Hot reload cache	Multiplier, valid range `0.3` to `2.0`; invalid values fall back to `0.6`.
`window_decorations`	string/null	`client`	Startup	`client` draws Paneflow chrome; `server` delegates to the OS compositor.
`window_backdrop`	string/null	`auto`	Startup	`auto`, `mica`, `blurred`, `acrylic`, `transparent`, `opaque`, or `off`. `PANEFLOW_WINDOW_BACKDROP` overrides for one launch.
`windows_terminal_material`	boolean/null	`false`	Window/terminal render	Windows-only terminal background material toggle. Ignored on other platforms.
`windows_chrome_material`	boolean/null	`false`	Window/chrome render	Windows-only native material in the primary navigation card. Ignored on other platforms.
`macos_chrome_material`	boolean/null	`true`	Window/chrome render	macOS-only native Sidebar material in the primary navigation card. Ignored on other platforms.
`option_as_meta`	boolean/null	`true`	New terminal	Sends Alt/Option as ESC-prefix Meta. Set `false` on macOS when Option should type Unicode characters.
`shell_integration`	boolean/null	`true`	New terminal	Enables Paneflow shell snippets for OSC 7 CWD and OSC 133 command marks.
`agent_stall_detection`	boolean/null	`true`	Runtime sweep	Detects Thinking agents with no hook activity past the threshold.
`agent_stall_threshold_secs`	integer/null	`60`	Runtime sweep	Range `30` to `86400`; checked by a 30 second sweep.
`review_prefill_delay_ms`	integer/null	`2000`	Review launch	Delay before auto-filling the review prompt into a fresh CLI. Range `250` to `10000`.
`submit_paste_delay_ms`	integer/null	`70`	IPC send	Floor delay between bracketed paste and Enter for `paneflow send --submit`. Range `10` to `5000`.
`external_editor`	string/null	`auto`	Next open action	`auto`, `system`, `zed`, `cursor`, `windsurf`, or `code`.
`shortcuts`	object	`{}`	Hot reload	Maps keystrokes to action names. See shortcuts and actions.
`terminal`	object/null	defaults below	Mixed	Namespaced terminal renderer and PTY settings.
`commands`	array	`[]`	Settings/Run	Command palette entries and workspace templates.
`claude_code_bypass_permissions`	boolean/null	`false`	Next Claude launch	Adds `--permission-mode bypassPermissions` to the Claude Code launcher. High-risk opt-in.
`ai_unrestricted`	boolean/null	`false`	Per IPC call	Allows trusted conductors to submit to peer panes without `PANEFLOW_IPC_SCRIPTING`. Every write is traced.
`ai_injection_fence`	boolean/null	`true`	Per read call	Wraps `surface.read` output in an untrusted-output fence by default.
`agent_panel`	object/null	defaults below	Agents UI	Agents-view display, profiles, and notification preferences.
`tool_permissions`	object	`{}`	Permission checks	Per-tool always-allow and always-deny input patterns.
`telemetry`	object/null	`{ "enabled": null }`	Startup/consent	Desktop telemetry consent. `PANEFLOW_NO_TELEMETRY=1` overrides it.

Agent launcher buttons

Each button key is boolean/null. null or omission auto-detects the CLI binary. false hides the button. true forces it visible.

Key	Agent
`claude_code_button_visible`	Claude Code
`codex_button_visible`	Codex
`opencode_button_visible`	OpenCode
`pi_button_visible`	Pi
`hermes_agent_button_visible`	Hermes Agent
`grok_button_visible`	Grok
`amp_button_visible`	Amp
`cursor_button_visible`	Cursor
`gemini_button_visible`	Gemini
`kiro_button_visible`	Kiro
`antigravity_button_visible`	Antigravity
`copilot_button_visible`	Copilot
`codebuddy_button_visible`	CodeBuddy
`factory_button_visible`	Factory
`qoder_button_visible`	Qoder
`openclaw_button_visible`	OpenClaw

`terminal`

Key	Type	Default	Applied	Notes
`terminal.backend`	string	`auto`	New session	`auto`, `ghostty`, or `alacritty`. Standard Linux builds and supported Windows x64 MSVC builds select Ghostty for `auto`; `ghostty` requests it explicitly and `alacritty` is the rollback. macOS and builds without the target's native Ghostty feature use Alacritty. Unknown runtime values fail safe to Alacritty. Applies only to new sessions.
`terminal.ligatures`	boolean/null	`false`	Hot reload cache	Enables programming ligatures when the active font supports them.
`terminal.integrated_glyphs`	boolean/null	`true`	Hot reload	Draws built-in block glyphs as filled quads.
`terminal.color_emoji`	boolean/null	`true`	Hot reload	Uses the platform color-emoji path.
`terminal.cursor_color`	string/null	theme cursor	Hot reload/new terminal	`#RRGGBB`, `RRGGBB`, `#RGB`, or `RGB`.
`terminal.scrollback_lines`	integer/null	`10000`	New terminal	Range `100` to `100000`. Review terminals cap at `2000`; cached terminals cap at `1000`.
`terminal.cursor_shape`	string/null	`block`	New terminal	`vintage`, `block`, `beam`, `underline`, `double_underline`, or `hollow`.
`terminal.cursor_blink`	string/null	`terminal_controlled`	New terminal	`on`, `off`, or `terminal_controlled`.
`terminal.env`	object/null	none	New terminal	Environment variables injected into every new terminal. Per-surface `env` wins.
`terminal.scroll_multiplier`	number/null	`1.0`	New terminal view	Range `0.1` to `10.0`. Ignored in mouse-reporting and alternate-screen scroll paths.

`agent_panel`

Key	Type	Default	Notes
`agent_panel.max_content_width`	integer/null	`760`	Chat content width in pixels. Range `320` to `4000`.
`agent_panel.thinking_display`	string/null	`Auto`	`Auto`, `Preview`, `AlwaysExpanded`, or `AlwaysCollapsed`.
`agent_panel.profiles`	object	`{}`	Named profile map. Keys are profile names.
`agent_panel.default_profile`	string/null	none	Profile selected by default when present.
`agent_panel.notify_when_agent_waiting`	string/null	`PrimaryScreen`	`PrimaryScreen`, `AllScreens`, or `Never`.

Profile entries under agent_panel.profiles use this shape:

Key	Type	Default	Notes
`agent_panel.profiles.*.agent`	string/null	none	Preferred agent tag.
`agent_panel.profiles.*.model`	string/null	none	Preferred model label.
`agent_panel.profiles.*.mode`	string/null	none	Preferred mode label.
`agent_panel.profiles.*.effort`	string/null	none	Preferred reasoning-effort label.
`agent_panel.profiles.*.tools`	string array	`[]`	Preferred tool-kind keys shown by the profile.

`tool_permissions`

tool_permissions is keyed by tool kind, for example read, edit, or execute.

Key	Type	Default	Notes
`tool_permissions.*.always_allow`	string array	`[]`	Substring patterns that auto-allow matching tool inputs.
`tool_permissions.*.always_deny`	string array	`[]`	Substring patterns that auto-deny matching tool inputs.

`commands`

commands entries back both simple shell commands and Settings > Workspaces templates. A command entry must have name; workspace and command are mutually exclusive.

Key	Type	Default	Notes
`commands[].name`	string	required	Display name. Must not be blank.
`commands[].description`	string/null	none	Human-readable description.
`commands[].keywords`	string array	`[]`	Fuzzy-search keywords.
`commands[].workspace`	object/null	none	Workspace template.
`commands[].command`	string/null	none	Simple shell command string.

Workspace template keys:

Key	Type	Default	Notes
`commands[].workspace.name`	string/null	command name	Workspace display name.
`commands[].workspace.cwd`	string/null	current cwd	Default workspace directory.
`commands[].workspace.layout_preset`	string/null	none	`even_h`, `even_v`, `main_vertical`, or `tiled`.
`commands[].workspace.color`	string/null	none	Six-digit hex accent color, no leading `#`.
`commands[].workspace.layout`	object/null	preset layout	Layout tree root.

Layout keys:

Key	Type	Notes
`commands[].workspace.layout.type`	string	`pane` or `split`.
`commands[].workspace.layout.surfaces`	array	Required for `pane` nodes.
`commands[].workspace.layout.direction`	string	Required for `split`: `horizontal` or `vertical`.
`commands[].workspace.layout.ratio`	number/null	Legacy binary split ratio, range `0.1` to `0.9`. Ignored when `ratios` exists.
`commands[].workspace.layout.ratios`	number array/null	Per-child ratios for N-ary layouts. Must match child count and sum near `1.0`.
`commands[].workspace.layout.children`	array	Required for `split`; minimum two layout nodes.

Surface keys inside a pane:

Key	Type	Default	Notes
`commands[].workspace.layout.surfaces[].surface_type`	string/null	`terminal`	Currently only terminal surfaces render.
`commands[].workspace.layout.surfaces[].name`	string/null	derived	Surface tab name.
`commands[].workspace.layout.surfaces[].custom_name`	string/null	none	User-assigned name that survives restart.
`commands[].workspace.layout.surfaces[].command`	string/null	shell	Command to run when the surface is created.
`commands[].workspace.layout.surfaces[].prompt`	string/null	none	Prompt to prefill after launching an agent command.
`commands[].workspace.layout.surfaces[].cwd`	string/null	workspace cwd	Per-surface working directory. Relative paths resolve against workspace cwd.
`commands[].workspace.layout.surfaces[].env`	object/null	none	Extra environment variables. Wins over `terminal.env` on collision.
`commands[].workspace.layout.surfaces[].focus`	boolean/null	false	Gives this surface initial focus.
`commands[].workspace.layout.surfaces[].scrollback`	string/null	none	Saved plain-text scrollback restored with the surface.
`commands[].workspace.layout.surfaces[].agent`	string/null	none	Stable tag of the agent CLI last detected in the surface.
`commands[].workspace.layout.surfaces[].font_size`	number/null	global `font_size`	Per-surface font-size override, range `8.0` to `32.0`.

`telemetry`

Key	Type	Default	Notes
`telemetry.enabled`	boolean/null	`null`	`null` means unanswered, `true` means opted in, `false` means opted out.

Complete example

paneflow.json

{
"$schema": "https://github.com/arthjean/paneflow/raw/main/schemas/paneflow.schema.json",
"$schemaVersion": "1.0.0",
"theme": "One Dark",
"font_family": "Lilex",
"font_size": 13,
"line_height": 1.2,
"cell_width": 0.6,
"windows_chrome_material": false,
"macos_chrome_material": true,
"terminal": {
  "backend": "auto",
  "ligatures": false,
  "scrollback_lines": 10000,
  "cursor_shape": "block"
},
"agent_panel": {
  "thinking_display": "Auto",
  "notify_when_agent_waiting": "PrimaryScreen"
},
"commands": [
  {
    "name": "API + Claude",
    "description": "Open the API project with Claude and tests",
    "workspace": {
      "name": "API",
      "cwd": "~/projects/api",
      "layout_preset": "even_h",
      "layout": {
        "type": "pane",
        "surfaces": [
          {
            "name": "Claude",
            "agent": "claude_code",
            "command": "claude",
            "prompt": "Review the API changes"
          }
        ]
      }
    }
  }
]
}