Référence du schéma paneflow.json

paneflow.json est un fichier JSON propre à l'utilisateur. Toutes les clés sont optionnelles, et {} est une configuration valide. Le loader Rust et les résolveurs runtime sont la source du comportement ; le JSON Schema publié reflète les clés publiques pour la validation éditeur et l'autocomplétion.

Les clés top-level inconnues sont ignorées au runtime, mais signalées par le schéma dans les éditeurs. Une sauvegarde valide est rechargée par le watcher de config. Pendant le hot reload, un JSON invalide garde la dernière config valide au lieu de diffuser les defaults. Au démarrage, un fichier invalide retombe sur les defaults et logue un avertissement.

Emplacements

PANEFLOW_HOME déplace tout le dossier (config, session, worktrees, cache, binaires auxiliaires). Une configuration trouvée aux anciens emplacements (~/.config/paneflow, ~/Library/Application Support/paneflow, %APPDATA%\paneflow) est copiée dans ~/.paneflow au premier lancement.

Schéma éditeur

Ajoute ceci en haut du fichier pour l'autocomplétion dans VS Code, Zed, les IDE JetBrains, Helix et les autres éditeurs compatibles JSON Schema :

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

Clés top-level

Boutons de lancement d'agents

Chaque clé de bouton est boolean/null. null ou l'omission auto-détecte le binaire CLI. false masque le bouton. true force son affichage.

Sous Windows, la palette de pane, le menu New pane et l'écran d'accueil ne proposent que Claude Code, Codex, Amp, Gemini et Copilot, les runtimes qui déclarent le support de Windows, et masquent les entrées agent_profiles basées sur les autres. Linux et macOS gardent tous les agents ci-dessous.

terminal

agent_panel

agents

worktrees

Paneflow crée un worktree git quand tu ouvres une branche depuis la palette « New pane », le menu contextuel d'un onglet ou paneflow up. Rien n'est écrit dans le checkout : le marqueur de propriété vit dans le git dir propre au worktree (.git/worktrees/<name>/ dans le dépôt principal), donc git status reste propre et le marqueur disparaît avec le worktree. Settings > Worktrees édite les mêmes clés et liste les worktrees que Paneflow gère.

Laisser le nom de branche vide dans la palette crée un checkout détaché sur la base choisie, nommé <base>-<sha7> ; « Create branch here… » dans le menu contextuel de l'onglet le transforme en branche plus tard, en gardant les modifications non commitées.

Un fichier .worktreeinclude à la racine du dépôt liste les fichiers et dossiers ignorés par git à copier dans chaque nouveau worktree, un chemin par ligne relatif à la racine, # pour les commentaires, / final optionnel pour les dossiers. Sans ce fichier, Paneflow copie les .env* de premier niveau et AGENTS.override.md s'ils existent. Un fichier déjà présent dans le worktree n'est jamais écrasé.

Avant de supprimer un worktree géré, automatiquement ou à la main, Paneflow sauvegarde ses modifications non commitées dans un commit de snapshot sous refs/paneflow/snapshots/ dans le dépôt principal : éditions suivies, nouveaux fichiers et la branche courante. Settings > Worktrees liste les snapshots ; Restore recrée le worktree avec ces modifications non commitées sur la même branche, Delete supprime la ref. Un worktree propre ne laisse aucun snapshot.

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

agent_profiles

agent_profiles est une liste. Chaque entrée ajoute un item de lancement qui exécute l'un des agents intégrés avec des variables d'environnement et des arguments en plus. Les profils apparaissent dans la palette de pane à côté des agents intégrés, et gardent le suivi de statut, les hooks et les sessions de l'agent de base. Settings > Agents > Profiles édite la même liste.

Une entrée avec un tag d'agent inconnu, un nom vide ou un token non sûr est ignorée avec un avertissement ; les autres profils se chargent quand même.

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

commands

Les entrées commands alimentent à la fois les commandes shell simples et les modèles Settings > Workspaces. Une entrée doit avoir name; workspace et command sont mutuellement exclusifs.

Clés d'un modèle de workspace :

Clés de layout :

Clés de surface dans un panneau :

telemetry

Exemple complet

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