paneflow.json Schema-Referenz

paneflow.json ist eine benutzerspezifische JSON-Datei. Alle Schlüssel sind optional, und {} ist eine gültige Konfiguration. Der Rust-Config- Loader und die Runtime-Resolver sind die Quelle des Verhaltens; das veröffentlichte JSON Schema spiegelt die öffentlichen Schlüssel für Editor-Validierung und Autovervollständigung.

Unbekannte Top-Level-Schlüssel werden zur Runtime ignoriert, aber vom Schema in Editoren markiert. Ein gültiges Speichern wird vom Config- Watcher neu geladen. Bei Hot Reload behält ungültiges JSON die letzte gültige Konfiguration, statt Defaults zu senden. Beim Start fällt eine ungültige Datei auf Defaults zurück und schreibt eine Warnung ins Log.

File locations

PANEFLOW_HOME verschiebt das ganze Verzeichnis (Konfiguration, Session, Worktrees, Cache, Hilfsbinärdateien). Eine Konfiguration an den früheren Orten (~/.config/paneflow, ~/Library/Application Support/paneflow, %APPDATA%\paneflow) wird beim ersten Start nach ~/.paneflow kopiert.

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 legt einen Git-Worktree an, wenn du einen Branch aus der Palette "New pane", dem Kontextmenü eines Tabs oder paneflow up öffnest. In den Checkout wird nichts geschrieben: die Besitzmarkierung liegt im eigenen Git-Verzeichnis des Worktrees (.git/worktrees/<name>/ im Hauptrepository), git status bleibt sauber, und die Markierung verschwindet mit dem Worktree. Settings > Worktrees bearbeitet dieselben Schlüssel und listet die verwalteten Worktrees.

Bleibt der Branch-Name in der Palette leer, entsteht ein detached Checkout auf der gewählten Basis mit dem Namen <base>-<sha7>; "Create branch here…" im Kontextmenü des Tabs macht später einen Branch daraus und behält uncommittete Änderungen.

Eine Datei .worktreeinclude im Repository-Root listet die von Git ignorierten Dateien und Verzeichnisse, die in jeden neuen Worktree kopiert werden, ein Pfad pro Zeile relativ zum Root, # für Kommentare, abschließender / bei Verzeichnissen optional. Ohne die Datei kopiert Paneflow die obersten .env* und AGENTS.override.md, sofern vorhanden. Eine im Worktree bereits vorhandene Datei wird nie überschrieben.

Bevor ein verwalteter Worktree entfernt wird, automatisch oder von Hand, sichert Paneflow seine uncommitteten Änderungen als Snapshot-Commit unter refs/paneflow/snapshots/ im Hauptrepository: verfolgte Änderungen, neue Dateien und den aktuellen Branch. Settings > Worktrees listet die Snapshots; Restore legt den Worktree mit diesen Änderungen uncommitted auf demselben Branch neu an, Delete verwirft die Ref. Ein sauberer Worktree hinterlässt keinen Snapshot.

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

agent_profiles

agent_profiles ist eine Liste. Jeder Eintrag fügt dem Launcher einen Punkt hinzu, der einen der eingebauten Agenten mit zusätzlichen Umgebungsvariablen und Argumenten startet. Profile erscheinen in der Pane-Palette neben den eingebauten Agenten und behalten Statusverfolgung, Hooks und Sessions des Basis-Agenten. Settings > Agents > Profiles bearbeitet dieselbe Liste.

Ein Eintrag mit unbekanntem Agent-Tag, leerem Namen oder unsicherem Token wird mit einer Warnung übersprungen; die übrigen Profile laden trotzdem.

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