paneflow.json Schema Reference

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

PANEFLOW_HOME moves the whole directory (config, session, worktrees, cache, helper binaries). Configuration found at the previous locations (~/.config/paneflow, ~/Library/Application Support/paneflow, %APPDATA%\paneflow) is copied into ~/.paneflow on first launch.

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:

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

Top-level keys

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.

On Windows, the pane palette, the New pane menu, and the welcome screen offer only Claude Code, Codex, Amp, Gemini, and Copilot, the runtimes that declare Windows support, and hide agent_profiles entries based on the others. Linux and macOS keep every agent below.

terminal

agent_panel

worktrees

Paneflow creates a git worktree when you open a branch from the "New pane" palette, a tab's context menu, or paneflow up. Nothing is written inside the checkout: the ownership marker lives in the worktree's own git dir (.git/worktrees/<name>/ in the main repository), so git status stays clean and the marker disappears with the worktree. Settings > Worktrees edits the same keys and lists the worktrees Paneflow manages.

Leaving the branch name empty in the palette creates a detached checkout at the chosen base, named <base>-<sha7>; "Create branch here…" in the tab's context menu turns it into a branch later, keeping any uncommitted changes.

A .worktreeinclude file at the repository root lists the git-ignored files and directories to copy into every new worktree, one path per line relative to the root, # for comments, trailing / optional for directories. Without the file, Paneflow copies the top-level .env* files and AGENTS.override.md when they exist. A file that already exists in the worktree is never overwritten.

Before a managed worktree is removed, automatically or by hand, its uncommitted changes are saved as a snapshot commit under refs/paneflow/snapshots/ in the main repository: tracked edits, new files, and the branch it was on. Settings > Worktrees lists the snapshots; Restore recreates the worktree with those changes uncommitted on the same branch, Delete drops the ref. A clean worktree leaves no snapshot.

{
  "worktrees": {
    "dir": "~/worktrees",
    "auto_remove": true,
    "keep_limit": 15
  }
}

agent_profiles

agent_profiles is a list. Each entry adds a launcher item that runs one of the built-in agents with extra environment variables and arguments. Profiles show up in the pane palette next to the built-in agents, and keep the base agent's status tracking, hooks, and sessions. Settings > Agents > Profiles edits the same list.

An entry with an unknown agent tag, a blank name, or an unsafe token is skipped with a warning; the other profiles still load.

{
  "agent_profiles": [
    {
      "name": "Claude perso",
      "agent": "claude_code",
      "env": { "CLAUDE_CONFIG_DIR": "~/.claude-perso" },
      "args": ["--model", "opus"]
    }
  ]
}

commands

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

Workspace template keys:

Layout keys:

Surface keys inside a pane:

telemetry

Complete example

{
"$schema": "https://github.com/arthjean/paneflow/raw/main/schemas/paneflow.schema.json",
"$schemaVersion": "1.0.0",
"theme": "One Dark",
"font_family": "JetBrainsMono Nerd Font",
"font_size": 13,
"line_height": 1.0,
"cell_width": 1.0,
"windows_chrome_material": false,
"macos_chrome_material": false,
"terminal": {
  "ligatures": true,
  "scrollback_lines": 10000,
  "cursor_shape": "block"
},
"agent_panel": {
  "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"
          }
        ]
      }
    }
  }
]
}