Referencia del esquema paneflow.json

paneflow.json es un archivo JSON por usuario. Todas las claves son opcionales, y {} es una configuración válida. El loader Rust y los resolvers de runtime son la fuente del comportamiento; el JSON Schema publicado refleja las claves públicas para validación de editor y autocompletado.

Las claves top-level desconocidas se ignoran en runtime, pero el schema las marca en los editores. Un guardado válido se recarga con el watcher de configuración. Durante hot reload, un JSON inválido conserva la última configuración válida en vez de difundir defaults. En arranque, un archivo inválido cae a defaults y registra un warning.

File locations

PANEFLOW_HOME mueve todo el directorio (configuración, sesión, worktrees, caché, binarios auxiliares). La configuración encontrada en las ubicaciones anteriores (~/.config/paneflow, ~/Library/Application Support/paneflow, %APPDATA%\paneflow) se copia en ~/.paneflow en el primer arranque.

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 crea un worktree git cuando abres una rama desde la paleta "New pane", el menú contextual de una pestaña o paneflow up. No se escribe nada dentro del checkout: el marcador de propiedad vive en el git dir propio del worktree (.git/worktrees/<name>/ en el repositorio principal), así que git status sigue limpio y el marcador desaparece con el worktree. Settings > Worktrees edita las mismas claves y lista los worktrees que Paneflow gestiona.

Dejar vacío el nombre de rama en la paleta crea un checkout detached en la base elegida, llamado <base>-<sha7>; "Create branch here…" en el menú contextual de la pestaña lo convierte en rama más tarde, conservando los cambios sin commit.

Un archivo .worktreeinclude en la raíz del repositorio lista los archivos y directorios ignorados por git que se copian en cada worktree nuevo, una ruta por línea relativa a la raíz, # para comentarios, / final opcional en directorios. Sin el archivo, Paneflow copia los .env* de primer nivel y AGENTS.override.md si existen. Un archivo que ya existe en el worktree nunca se sobrescribe.

Antes de eliminar un worktree gestionado, automáticamente o a mano, Paneflow guarda sus cambios sin commit en un commit de snapshot bajo refs/paneflow/snapshots/ en el repositorio principal: ediciones de archivos rastreados, archivos nuevos y la rama actual. Settings > Worktrees lista los snapshots; Restore recrea el worktree con esos cambios sin commit en la misma rama, Delete descarta la ref. Un worktree limpio no deja snapshot.

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

agent_profiles

agent_profiles es una lista. Cada entrada añade un elemento de lanzamiento que ejecuta uno de los agentes integrados con variables de entorno y argumentos extra. Los perfiles aparecen en la paleta de paneles junto a los agentes integrados, y conservan el seguimiento de estado, los hooks y las sesiones del agente base. Settings > Agents > Profiles edita la misma lista.

Una entrada con un tag de agente desconocido, un nombre vacío o un token inseguro se omite con un aviso; los demás perfiles se cargan igualmente.

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