Skip to content
PaneflowPaneflow

Configuration

Customize Paneflow with a single paneflow.json file - default shell, theme, keybindings, window decorations, and more.

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?

OSPath
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:

json
{
  "$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.

What's next?