paneflow.json Schema-Referenz

Jeder paneflow.json-Schlüssel mit Typ, Default, Anwendungszeitpunkt und Runtime-Notizen.

Zuletzt aktualisiert am 2. September 2026

paneflow.json ist eine benutzerspezifische JSON-Datei. Alle Schlüssel sind optional, und {} ist eine gültige Konfiguration. Der Rust-Config- Loader und die Runtime-Resolver sind die Quelle des Verhaltens; das veröffentlichte JSON Schema spiegelt die öffentlichen Schlüssel für Editor-Validierung und Autovervollständigung.

Unbekannte Top-Level-Schlüssel werden zur Runtime ignoriert, aber vom Schema in Editoren markiert. Ein gültiges Speichern wird vom Config- Watcher neu geladen. Bei Hot Reload behält ungültiges JSON die letzte gültige Konfiguration, statt Defaults zu senden. Beim Start fällt eine ungültige Datei auf Defaults zurück und schreibt eine Warnung ins Log.

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	`Paneflow Dark`	Hot reload	The light or dark variant of one preset: Paneflow, Vercel, Claude, Cursor. Pre-preset names (`One Dark`, `PaneFlow Light`, `Vercel`, `Claude`, `Cursor`) still resolve. 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`.
`unfocused_pane_opacity`	number/null	`0.7`	Hot reload	Opacity of panes that do not hold focus, when a workspace has more than one pane. Range `0.15` to `1.0`; `1.0` disables the dim.
`reduce_motion`	boolean/null	`false`	Hot reload	Minimizes non-essential interface motion: hover transitions settle instantly and decorative animations render a static frame.
`sidebar_show`	object/null	all off	Hot reload	What a session tab row shows beyond its name: `branch` adds its git branch, `diffstat` adds its insertion and deletion counts, `pr` turns the branch icon into a pull-request glyph colored by the request's state when one exists, `indent_guide` draws a hairline under a workspace's folder icon down its tab rows. The first two read the tab's bound worktree, or its workspace's checkout when the tab is unbound; `pr` needs the `gh` CLI and answers for GitHub remotes only. Toggled from the rail's Customize Sidebar menu.
`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.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": {
  "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"
          }
        ]
      }
    }
  }
]
}