paneflow.json Schema Reference

Every key Paneflow recognises today, grouped by what it controls. All keys are optional and resolve to a sensible default when omitted. The authoritative source is the JSON Schema shipped with each release.

Core

The five most-asked-about keys.

How do I set default_shell?

Type: string (optional). Default: $SHELL.

{ "default_shell": "/bin/zsh" }

Paneflow resolves the value through a fallback chain: configured path (if executable) -> $SHELL -> /bin/sh. A configured shell that is missing or non-executable falls through to the next link and emits a log warning.

How do I set theme?

Type: string (optional). Default: "One Dark".

Built-in themes:

• "One Dark" - dark theme, default.
• "PaneFlow Light" - light theme.

{ "theme": "PaneFlow Light" }

Unknown names fall back to "One Dark" and emit a log warning. Themes hot-reload on file save (500 ms mtime polling) - no restart needed.

How do I set window_decorations?

Type: "client" | "server" (optional). Default: "client".

{ "window_decorations": "client" }

"client" draws a custom title bar (CSD); "server" defers to the OS compositor (SSD). The default is "client" on all platforms; there is no OS-specific override. Read once at startup - changes require a restart.

How do I set shortcuts?

Type: object mapping keystroke -> action_name (optional). Default: empty object (built-in defaults apply).

{
  "shortcuts": {
    "ctrl+shift+t": "new_tab",
    "ctrl+shift+w": "close_pane"
  }
}

Keys are keystroke strings; values are action names. See the full keybindings reference for the action vocabulary. User entries override the built-in defaults with last-write-wins semantics.

How do I set commands?

Type: array of command definitions (optional). Default: empty array.

{
  "commands": [
    {
      "name": "Open API",
      "workspace": { "cwd": "~/projects/api" }
    }
  ]
}

Typography

The three typography keys landed in an early 0.2.x release; the project did not pin per-key release tags, so the exact since value is approximate.

How do I set font_family?

Type: string (optional). Default: platform monospace fallback chain.

{ "font_family": "JetBrains Mono" }

Paneflow tries the configured family first, then falls back to the first installed monospace family it can locate.

How do I set font_size?

Type: number (optional, pixels). Default: 14.

{ "font_size": 14 }

How do I set line_height?

Type: number (optional, multiplier in the range 1.0–2.5). Default: 1.3.

{ "line_height": 1.3 }

Values outside the 1.0–2.5 range are rejected with a log warning and the default is used instead.

Input

How do I set option_as_meta?

Type: boolean (optional, Unix). Default: true.

{ "option_as_meta": false }

When true (the default), the Alt key (Linux) or Option key (macOS) sends an ESC prefix - the standard Meta-key behavior used by Emacs, Vim, and most terminal applications. Set to false if you want Option to produce native Unicode characters on macOS (e.g., Option+e -> é).

AI agent buttons

Toggles for the per-agent quick-launch buttons in the pane title bar.

How do I set claude_code_button_visible?

Type: boolean (optional). Default: true.

{ "claude_code_button_visible": false }

How do I set claude_code_bypass_permissions?

Type: boolean (optional). Default: false.

{ "claude_code_bypass_permissions": true }

When true, the Claude Code launcher invokes the CLI with --dangerously-skip-permissions. Off by default for safety.

How do I set codex_button_visible?

Type: boolean (optional). Default: true.

{ "codex_button_visible": false }

How do I set opencode_button_visible?

Type: boolean (optional). Default: true.

{ "opencode_button_visible": false }

Telemetry

How do I set telemetry?

Type: object { enabled: boolean | null } (optional). Default: { "enabled": null } (prompt on first launch).

{ "telemetry": { "enabled": false } }

Set enabled: false to disable all PostHog reporting. Set enabled: true to opt in without the first-launch prompt.

Terminal

How do I set terminal.ligatures?

Type: boolean inside the terminal object (optional). Default: false.

{ "terminal": { "ligatures": true } }

Enables programming ligatures for fonts that ship them (Fira Code, JetBrains Mono, Iosevka, etc.). The font must contain the ligature glyphs for the feature to take effect.

A complete example

{
  "$schema": "https://github.com/ArthurDEV44/paneflow/raw/main/schemas/paneflow.schema.json",
  "default_shell": "/bin/zsh",
  "theme": "One Dark",
  "font_family": "JetBrains Mono",
  "font_size": 14,
  "line_height": 1.3,
  "window_decorations": "client",
  "option_as_meta": true,
  "shortcuts": {},
  "terminal": { "ligatures": false },
  "telemetry": { "enabled": null },
  "claude_code_button_visible": true,
  "claude_code_bypass_permissions": false,
  "codex_button_visible": true,
  "opencode_button_visible": true,
  "commands": []
}

For the live schema definition see paneflow.schema.json.