Paneflow reads a single JSON file at startup: paneflow.json. Every
key is optional and has a sensible default, so an empty {} is a
valid config. The full reference, including types, defaults, apply
timing, and runtime notes, lives on the schema page.
TL;DR. One file: paneflow.json. Every key is optional, {} is valid, unknown keys are ignored. Pin the $schema line below to get autocomplete in your editor.
Where is paneflow.json?
| OS | Path |
|---|---|
| Linux and macOS | ~/.paneflow/paneflow.json |
| Windows | %USERPROFILE%\.paneflow\paneflow.json |
PANEFLOW_HOME moves the whole directory (config, session, worktrees, cache,
helper binaries). Configuration found at the previous locations
(~/.config/paneflow, ~/Library/Application Support/paneflow,
%APPDATA%\paneflow) is copied into ~/.paneflow on first launch.
If the file does not exist on first launch, Paneflow boots with all defaults. Create the file at the path above to start customizing.
Editor autocomplete with JSON Schema
Pin a $schema reference to get instant autocomplete and type
checking in VS Code, JetBrains, Zed, Helix, or any editor with a
JSON Schema language server:
{
"$schema": "https://github.com/arthjean/paneflow/raw/main/schemas/paneflow.schema.json",
"theme": "One Dark"
}The schema is published with every release and tracks the exact set of keys the running build accepts.
How does Paneflow handle unknown keys?
Paneflow is lenient at runtime: unknown top-level keys are silently ignored, and missing keys resolve to their defaults. This keeps your config forward-compatible across releases - dropping in a key from a newer build never breaks an older Paneflow binary.
The JSON Schema additionally rejects unknown keys at edit time
(additionalProperties: false), so your editor flags typos before
you save. The runtime stays permissive on purpose.
Spaces
spaces groups workspaces into named contexts, for example work and personal
projects. Each entry needs an id (a UUID) and a name, and takes an
optional color and env; Settings > Spaces also
records the space's image as avatar. Up to 9 spaces are allowed next to the
implicit Default space. Hand edits apply without a restart. See the
schema page for the limits.
A space's env is set on every terminal of its workspaces, with this
precedence, lowest first: terminal.env, the space's env, an agent
profile's env, then the surface's own env. Paneflow's own git, gh,
clone, and tab-naming processes for those workspaces receive a fixed
subset of it, listed on the schema page.
A terminal reads the environment when it starts: a change applies to the
terminals opened after it, and a shell that exports the same variable from
its rc file, for example .zshrc, overrides the space's value.