paneflow.json 模式参考

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

PANEFLOW_HOME 会移动整个目录（配置、会话、worktree、缓存、辅助二进制文件）。 位于旧位置（~/.config/paneflow、~/Library/Application Support/paneflow、 %APPDATA%\paneflow）的配置会在首次启动时复制到 ~/.paneflow。

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

agents

worktrees

当你从「New pane」调色板、标签页的上下文菜单或 paneflow up 打开一个分支时，Paneflow 会创建一个 git worktree。检出目录内不会写入任何东西：所有权标记位于该 worktree 自己的 git dir（主仓库中的 .git/worktrees/<name>/），因此 git status 保持 干净，标记也随 worktree 一起消失。Settings > Worktrees 编辑同样的键，并列出 Paneflow 管理的 worktree。

在调色板中留空分支名会在所选基础上创建一个 detached 检出，命名为 <base>-<sha7>；之后可通过标签页右键菜单中的「Create branch here…」把它变成 分支，未提交的更改会保留。

仓库根目录下的 .worktreeinclude 文件列出要复制到每个新 worktree 的 git 忽略 文件和目录，每行一个相对根目录的路径，# 为注释，目录末尾的 / 可选。没有该 文件时，Paneflow 会复制顶层的 .env* 以及存在的 AGENTS.override.md。worktree 中已存在的文件绝不会被覆盖。

无论自动还是手动，删除受管 worktree 之前，Paneflow 都会把它的未提交更改保存为 主仓库 refs/paneflow/snapshots/ 下的一个快照提交：已跟踪文件的修改、新文件， 以及当时所在的分支。Settings > Worktrees 列出这些快照；Restore 会在同一分支上 重建 worktree 并让这些更改保持未提交状态，Delete 则丢弃该 ref。干净的 worktree 不会留下快照。

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

agent_profiles

agent_profiles 是一个列表。每个条目都会添加一个启动项，以额外的环境变量和 参数运行某个内置智能体。这些配置会与内置智能体一起出现在 pane 调色板中，并沿用基础智能体的状态跟踪、hooks 和会话。 Settings > Agents > Profiles 编辑同一列表。

智能体标签未知、名称为空或包含不安全 token 的条目会被跳过并给出警告；其他配置 仍会加载。

{
  "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"
          }
        ]
      }
    }
  }
]
}