paneflow.json スキーマリファレンス

paneflow.json はユーザー単位の JSON ファイルです。すべてのキーは 省略可能で、{} も有効な設定です。挙動のソースは Rust の config loader と runtime resolver です。公開 JSON Schema は、エディタの validation と autocomplete 用に公開キーを反映します。

未知の top-level key は runtime では無視されますが、エディタでは schema によって検出されます。有効な保存は config watcher によって reload されます。 Hot reload 中に JSON が壊れている場合、defaults を配信せず直前の有効な config を維持します。起動時にファイルが無効な場合は 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

Paneflow は「New pane」パレット、タブのコンテキストメニュー、paneflow up からブランチを開くと git worktree を作ります。チェックアウトの中には何も書きません。所有マーカーは worktree 自身の git dir（メインリポジトリの .git/worktrees/<name>/）にあり、 git status はきれいなままで、マーカーは worktree と一緒に消えます。 Settings > Worktrees で同じキーを編集でき、Paneflow が管理する worktree を一覧できます。

パレットでブランチ名を空のままにすると、選んだベースで detached なチェックアウトが <base>-<sha7> という名前で作られます。タブのコンテキストメニューの 「Create branch here…」で後からブランチにでき、未コミットの変更は保持されます。

リポジトリのルートに置いた .worktreeinclude は、新しい worktree にコピーする git-ignored なファイルやディレクトリを 1 行 1 パス（ルートからの相対パス）で 列挙します。# はコメント、ディレクトリの末尾 / は省略可能です。ファイルが ない場合、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 はリストです。各エントリは、組み込みエージェントのいずれかを 追加の環境変数と引数つきで起動する launcher 項目を追加します。プロファイルは pane パレットに組み込みエージェントと並んで表示され、ベースの エージェントのステータス追跡、hooks、セッションをそのまま使います。 Settings > Agents > Profiles でも同じリストを編集できます。

未知のエージェントタグ、空の名前、安全でないトークンを含むエントリは警告つきで スキップされ、他のプロファイルは読み込まれます。

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