paneflow.json Schema Reference

Every paneflow.json key with its type, default, apply timing, and runtime notes.

Last updated on July 2, 2026

paneflow.json is a per-user JSON file. All keys are optional, and {} is a valid config. The Rust config loader and runtime resolvers are the source of behavior; the published JSON Schema mirrors the public keys for editor validation and autocomplete.

Unknown top-level keys are ignored by the runtime but flagged by the schema in editors. A valid save is reloaded by the config watcher. During hot reload, invalid JSON keeps the previous valid config instead of broadcasting defaults. Startup reads an invalid file as defaults and logs a 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/ArthurDEV44/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.
`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 sidebar and title-bar material toggle. 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.
`rosetta_enabled`	boolean/null	`true`	UI render	Master switch for the in-app Rosetta card only.
`rosetta_show_passive`	boolean/null	`false`	UI render	Shows passive running-only Rosetta rows when enabled.
`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/ArthurDEV44/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,
"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"
          }
        ]
      }
    }
  }
]
}