Skip to content
PaneflowPaneflow

paneflow.json Schema Reference

Every paneflow.json key with its type, default, apply timing, and runtime notes.

paneflow.json is a per-user JSON file. All keys are optional, and {} is a valid config. The Rust config loader and runtime resolvers are the source of behavior; the published JSON Schema mirrors the public keys for editor validation and autocomplete.

Unknown top-level keys are ignored by the runtime but flagged by the schema in editors. A valid save is reloaded by the config watcher. During hot reload, invalid JSON keeps the previous valid config instead of broadcasting defaults. Startup reads an invalid file as defaults and logs a warning.

File locations

PlatformPath
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.

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:

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

Top-level keys

KeyTypeDefaultAppliedNotes
$schemastringnoneEditor onlyPoints editors to the published schema. Ignored by Paneflow.
$schemaVersionstring1.0.0Startup/reloadUnknown versions warn but do not block loading.
default_shellstring/nullPlatform shell fallbackNew terminalUnix: configured -> $SHELL -> /bin/sh. Windows: configured -> pwsh.exe -> powershell.exe -> %ComSpec% -> C:\Windows\System32\cmd.exe -> cmd.exe.
themestring/nullPaneflow DarkHot reloadThe light or dark variant of one preset: Paneflow, Vercel, Claude, Cursor, Tailwind. Pre-preset names (One Dark, PaneFlow Light, Vercel, Claude, Cursor) still resolve. Runtime lookup is case-insensitive.
theme_modestring/nulldarkHot reloadlight and dark force the matching bundled theme; system follows the OS window appearance.
font_familystring/nullbundled JetBrainsMono Nerd FontHot reload cacheAccepts .PaneflowMono, JetBrainsMono NF, JetBrainsMono NFM, .PaneflowSans, embedded font names, or installed monospace families.
font_fallbacksstring array/nullGPUI fallback stackHot reload cacheOrdered extra fallback families for glyphs missing from font_family.
font_sizenumber/null13.0Hot reload cachePoints, valid range 8.0 to 32.0; invalid values fall back to 13.0.
font_weightstring/nullnormalHot reload cacheOne of thin, extra_light, light, semi_light, normal, medium, semi_bold, bold, extra_bold, black, extra_black.
line_heightnumber/null1.0Hot reload cacheMultiplier of the font's own line height (ascent, descent, and line gap), valid range 0.8 to 2.5. The cell is rounded to whole device pixels.
cell_widthnumber/null1.0Hot reload cacheMultiplier of the font's advance, valid range 0.8 to 2.0. The cell is rounded to whole device pixels.
unfocused_pane_opacitynumber/null1.0Hot reloadOpacity of panes that do not hold focus, when a workspace has more than one pane. Range 0.15 to 1.0; 1.0 disables the dim.
reduce_motionboolean/nullfalseHot reloadMinimizes non-essential interface motion: hover transitions settle instantly and decorative animations render a static frame. Trackpad scrolling in a terminal moves by whole lines instead of following the gesture by the pixel.
comfortable_densityboolean/nulltrueHot reloadSeparates the panes of a workspace into rounded cards with a gutter between them. false joins them edge to edge with a 1 px divider that keeps a 7 px grab area, and rounds only the outer corners of the grid and of the diff dock. Applies to the Rounded interface style only. Toggled from Settings > Appearance or the command palette.
interface_stylestring/nullclassicHot reloadLayout and shape language of the interface. classic lays the window out edge to edge, with the tabs of the top panes and of the dock in the title bar, and draws circular corners on a tight 6, 8, 12, and 14 px scale. rounded floats the panes as cards under a full-width title bar and draws continuous corners with generous radii, and circular corners on menus, select popups, and settings cards. The former value paneflow still selects rounded. Set from Settings > Appearance > Interface style or the command palette.
workspace_iconstring/nulldefaultHot reloadGlyph in front of each workspace row of the sidebar, closed while the workspace is folded and open while its tabs show. default is Paneflow's outlined folder. standard draws a disclosure chevron, right when folded and down when open, in place of a folder. metal is a filled glass folder, windows a yellow gradient folder, windows95 the 16-color pixel folder, and pixel an outlined pixel folder. The two pixel styles are sharpest at a display scale of 100 % or 200 %. Set from Settings > Appearance > Workspace icon or the command palette.
app_iconstring/nullglassHot reload on Windows and macOS; new windows on Linux X11Icon of the running app. glass is the installed violet glass icon; black and white draw the mark in horizontal bars on a black or a white tile; black-solid and white-solid draw its panes as solid shapes. Sixteen illustrated icons show the same mark in another material: aubergine, paper, midnight-matte, polar, melon, honeydew, berry, rainbow, solarwave, neon, phosphor, holo, amethyst, blueprint, chip, nostalgia. Windows shows it in Alt+Tab at once and points the shortcuts of your profile that open this Paneflow at it, the pinned taskbar one and the Start menu entry included, so the taskbar button follows at the next sign-in; macOS shows it in the Dock while Paneflow runs, and X11 as the window icon. Wayland ignores it. Set from Settings > Appearance > App icon. See App icon.
sidebar_showobject/nullstatus, shimmer, agents, agent_logo, agent_workspace, and agent_shimmer on, others offHot reloadWhat the sidebar rows show beyond their name: branch adds a checkout's git branch, diffstat adds its insertion and deletion counts, pr turns the branch icon into a pull-request glyph colored by the request's state when one exists, indent_guide draws a hairline under a workspace's folder icon down its tab rows. A checkout is shown once: the workspace row carries the branch and the counts of the workspace's own checkout, and a tab row carries them only when the tab is bound to a worktree of its own; grouped by status, every tab row carries its checkout's; pr needs the gh CLI and answers for GitHub remotes only. agents shows the Agents section at the bottom of the sidebar, the active space's agent sessions with the most urgent first; a value that is not a boolean counts as on. status shows agent status on workspace and tab rows: the Need you, Error, and Done badges, the working matrix, the title shimmer, and the status tooltip; false leaves the status to the Agents section, and a tab's pull request takes the freed place. agent_logo and agent_workspace choose what each Agents row shows: the agent's logo and the workspace name after the title; a row always shows its status. shimmer and agent_shimmer animate the title of a working agent, on tab rows and on Agents rows respectively: the title turns gray and a bright band sweeps across it; false keeps the title still in its usual color. agent_all_spaces (off by default) lists every space's agents in the Agents section instead of the active space's alone, the active space's first in each status group, each row from another space naming it after its workspace. agent_logo, agent_workspace, agent_shimmer, and agent_all_spaces are toggled from the Customize agent rows button at the right of the Agents header, the others from the rail's Customize Sidebar menu.
sidebar_group_bystring/nullfolderHot reloadHow the Workspaces sidebar groups its rows. folder lists each workspace as a folder row with its tabs under it. status lists the tabs of every workspace of the active space under status headings, in the order Need you, Error, Done, Working, Idle, each tab naming its workspace after its title; a tab takes the status of its most urgent agent, and Idle when it runs none. Grouping by status hides the Agents section, which would repeat the list, and adds a New tab button to the sidebar header that asks which workspace the tab opens in. Set from Customize sidebar > Group by or the command palette.
worktreesobject/nullsee belowHot reloadWhere Paneflow keeps the git worktrees it creates for branches and how it cleans them up: dir, auto_remove, keep_limit, for_new_branches. Settings > Worktrees edits the same keys.
window_decorationsstring/nullclientStartupclient draws Paneflow chrome; server delegates to the OS compositor.
window_backdropstring/nullautoStartupauto, mica, blurred, acrylic, transparent, opaque, or off. On Windows, blurred and acrylic set in the config resolve to auto; only PANEFLOW_WINDOW_BACKDROP applies blur there. On Linux, blurred asks a Wayland compositor that offers ext-background-effect or KDE's blur to blur what lies behind the window, along its rounded corners, while linux_chrome_material or linux_terminal_material makes it translucent; X11 and GNOME keep the translucent window unblurred. PANEFLOW_WINDOW_BACKDROP overrides for one launch.
windows_terminal_materialboolean/nullfalseWindow/terminal renderWindows-only terminal background material toggle. The Mica and Blended background styles set it to true, Themed to false. Ignored on other platforms.
windows_chrome_materialboolean/nullfalseWindow/chrome renderWindows-only native material in the primary navigation card. The Mica and Blended background styles set it to true, Themed to false. Ignored on other platforms.
windows_material_veilboolean/nullfalseWindow/chrome renderWindows-only. Switches the system backdrop from Mica to Acrylic, a blur of what lies behind the window, then paints a theme veil over it (0.72 on dark themes, 0.80 on light ones) and a 0.35 shade on the terminal card, like the Linux material. The Blended background style sets it to true; Mica and Themed set it to false. Only matters while a Windows material is on. Ignored on other platforms.
macos_chrome_materialboolean/nullfalseWindow/chrome rendermacOS-only native Sidebar material in the primary navigation card. The Blended background style sets it to true, Themed to false. Ignored on other platforms.
linux_terminal_materialboolean/nullfalseWindow/terminal renderLinux-only translucent terminal card over the window veil, so a compositor blur shows through. The Blended background style sets it to true, Themed to false. Ignored on other platforms.
linux_chrome_materialboolean/nullfalseWindow/chrome renderLinux-only translucent veil behind the sidebar and the title bar, so a compositor blur shows through. The Blended background style sets it to true, Themed to false. Ignored on other platforms.
option_as_metaboolean/nulltrue on Linux and Windows, false on macOSHot reloadSends Alt/Option as ESC-prefix Meta. On macOS, true makes Option plus a letter send Meta instead of composing a character; keep false when Option should type Unicode characters. A config reload applies it to open terminals.
shell_integrationboolean/nulltrueNew terminalEnables Paneflow shell snippets for OSC 7 CWD and OSC 133 command marks.
editorobject/nulldefaults belowHot reloadHow the code editor and the dock's file viewers show a file: minimap, scrollbar, word_wrap, markdown_rendered, and csv_table. See editor.
automationobject/nullall offHot reloadBackground work run after an agent turn: tab_auto_naming summarizes the session's recent exchange into a 2-5 word tab name through the agent's own CLI (claude -p, codex exec, opencode run, pi --print) with tools disabled, at most once per three minutes per session and only when the conversation grew. A name you typed is never replaced; "Reset name" reopens the tab to it.
submit_paste_delay_msinteger/null70IPC sendFloor delay between bracketed paste and Enter for paneflow send --submit. Range 10 to 5000.
external_editorstring/nullautoNext open actionEditor that opens file links, including terminal file links: auto, system, zed, cursor, webstorm, code, or visual_studio. auto uses $VISUAL, then $EDITOR, then the first known editor on PATH; system always uses the OS opener. A named editor that is not on PATH falls back to auto, and so does the former value windsurf.
shortcutsobject{}Hot reloadMaps keystrokes to action names. See shortcuts and actions.
terminalobject/nulldefaults belowMixedNamespaced terminal renderer and PTY settings.
commandsarray[]Settings/RunCommand palette entries and workspace templates.
agent_profilesarray[]Hot reloadCustom launcher entries that run a built-in agent with extra environment variables and arguments, for example a second Claude Code account through CLAUDE_CONFIG_DIR. Settings > Agents > Profiles edits the same list.
spacesarray[]Hot reloadNamed groups of workspaces, at most 9. The sidebar lists only the active space's workspaces. See spaces.
claude_code_bypass_permissionsboolean/nullfalseNext Claude launchAdds --permission-mode bypassPermissions to the Claude Code launcher. High-risk opt-in.
ai_unrestrictedboolean/nullfalsePer IPC callAllows trusted conductors to submit to peer panes without PANEFLOW_IPC_SCRIPTING.
ai_injection_fenceboolean/nulltruePer read callWraps surface.read output in an untrusted-output fence by default.
on_quitask, keep, stop, nullaskAt quitWhat quitting does while hosted sessions run: ask opens the quit dialog, keep leaves every session running, stop stops them all and shuts the host down. With no live session the app exits and shuts the idle host down.
agent_panelobject/nulldefaults belowAgents UIAgents-view notification preferences.
agentsobject/nulldefaults belowRestore and next launchAgent conversation restore and Claude Code session-id preassignment.
usageobject/nulldefaults belowNext integration refreshSubscription usage: whether Paneflow relays Claude Code plan limits.
telemetryobject/null{ "enabled": null }Startup/consentDesktop telemetry consent. PANEFLOW_NO_TELEMETRY=1 overrides it.

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.

KeyAgent
claude_code_button_visibleClaude Code
codex_button_visibleCodex
opencode_button_visibleOpenCode
pi_button_visiblePi
hermes_agent_button_visibleHermes Agent
grok_button_visibleGrok
amp_button_visibleAmp
gemini_button_visibleGemini
copilot_button_visibleCopilot
factory_button_visibleFactory
openclaw_button_visibleOpenClaw
muse_button_visibleMuse Code
fx_button_visiblefx (Linux and macOS)

terminal

KeyTypeDefaultAppliedNotes
terminal.ligaturesboolean/nulltrueHot reload cacheEnables programming ligatures when the active font supports them.
terminal.integrated_glyphsboolean/nulltrueHot reloadDraws built-in block glyphs as filled quads.
terminal.color_emojiboolean/nulltrueHot reloadUses the platform color-emoji path.
terminal.cursor_colorstring/nulltheme cursorHot reload/new terminal#RRGGBB, RRGGBB, #RGB, or RGB.
terminal.scrollbarboolean/nulltrueNew terminal viewOverlay scrollbar shown while scrolling or hovering the right edge of a pane.
terminal.scrollback_linesinteger/null10000New terminalRange 100 to 100000. Cached terminals cap at 1000.
terminal.cursor_shapestring/nullblockNew terminalvintage, block, beam, underline, double_underline, or hollow.
terminal.osc52_clipboardstring/nullcopyNew terminal viewAvailable since v0.17.5. copy lets the focused terminal write the system clipboard through OSC 52; off refuses all OSC 52 writes. OSC 52 clipboard reads are always denied. Existing terminal views keep their policy until recreated.
terminal.open_links_instring/nulldockImmediateAvailable since v0.20.0. Where a clicked code path such as src/main.rs:12 opens: dock opens the file in the Files dock at that line, external_editor opens it in the external editor. Holding Shift while clicking picks the other one. Markdown paths keep opening in a pane.
terminal.xt_checksum_reportboolean/nullfalseNew sessionAvailable since v0.17.7. Answers DECRQCRA checksum requests (CSI Pi ; Pg ; Pt ; Pl ; Pb ; Pr * y), which conformance suites such as vttest and esctest rely on. Off by default because a running program can checksum the screen one cell at a time and so read back everything on it, including output from other programs. While it is off, XTCHECKSUM (CSI Ps # y) is ignored as well. The session host reads it each time it starts a session.
terminal.xt_checksum_extensioninteger/null0New sessionAvailable since v0.17.7. How the DECRQCRA checksum is calculated, with the bits of XTCHECKSUM and xterm's checksumExtension: 1 keeps the result positive, 2 leaves out cell video attributes, 4 counts blanks, 8 counts cells never written to as spaces, 16 uses full codepoints instead of DEC 8-bit values. 0 is the calculation of a real DEC terminal. Range 0 to 31. A value outside it, such as 32, -1, 1.5, or "4", drops only this key: it falls back to 0 with a warning that names the key and the range, and the rest of the file still applies, at startup and on reload. A full reset (ESC c) returns to this value.
terminal.cursor_blinkstring/nullterminal_controlledNew terminalon, off, or terminal_controlled.
terminal.envobject/nullnoneNew terminalEnvironment variables injected into every new terminal. Per-surface env wins. Values are passed through verbatim: no ~ and no $NAME expansion, unlike agent_profiles.*.env. Keys Paneflow sets for every terminal, such as TERM, ZDOTDIR, and the PANEFLOW_* variables, are ignored and logged once. LANG defaults to en_US.UTF-8 only when LANG, LC_ALL, and LC_CTYPE are all unset.
terminal.scroll_multipliernumber/null1.0New terminal viewRange 0.1 to 10.0. Ignored in mouse-reporting and alternate-screen scroll paths.
terminal.minimum_contrastnumber/nullAuto (60)Hot reloadMinimum APCA lightness contrast (Lc) enforced between text and its cell background, on the colors a program chose (truecolor and palette indices 16 to 255). The theme's sixteen ANSI colors, foreground, and background are never corrected. Unset means Auto, which is 60 on every theme; 0 turns the correction off; a negative or non-numeric value means Auto. Range 0 to 90.

editor

KeyTypeDefaultAppliedNotes
editor.minimapboolean/nullfalseHot reloadDraws a minimap of the file along the editor's right edge. Toggled from the editor's controls menu; the choice applies to every open file.
editor.scrollbarboolean/nulltrueHot reloadDraws the editor's vertical scrollbar. Toggled from the editor's controls menu; the choice applies to every open file.
editor.word_wrapboolean/nullfalseNext file openWraps long lines at the editor's width when a file opens, at the last space that fits. Word Wrap, at the top of the editor's controls menu, changes it for one tab only. Up, Down, Page Up, and Page Down move by visual row.
editor.markdown_renderedboolean/nullfalseHot reloadShows Markdown files rendered in the dock rather than as source. Show rendered markdown and Show markdown source in the file header set it for every Markdown file. A file opened at a requested line always shows its source.
editor.csv_tableboolean/nulltrueHot reloadShows .csv and .tsv files of up to 10 MB as a read-only table in the dock rather than as source. Show source and Show table in the file header set it for every delimited file; false opens them as editable text.

agent_panel

KeyTypeDefaultNotes
agent_panel.notify_when_agent_waitingstring/nullNeverPrimaryScreen, AllScreens, or Never. Also governs desktop notifications that terminal programs send with OSC 9 or OSC 777.

agents

KeyTypeDefaultNotes
agents.restore_conversationsboolean/nulltrueWhen a pane's hosted session did not survive, for instance after a reboot, Paneflow opens a shell in the recorded folder and types the runtime's resume command for the conversation last started in that pane. Set to false to only reopen the shell.
agents.update_methodsobject{}How Settings › Agents updates each agent's CLI, keyed by runtime slug such as claude-code or codex. auto (or no entry) uses the tool that installed it; self runs the agent's own updater; npm, bun, pnpm and yarn install its npm package globally with that tool; script reruns its official installer, through PowerShell on Windows and curl elsewhere. Choosing a tool other than the one that installed the CLI installs a second copy, and the copy first on PATH is the one that runs.
agents.claude_preassign_session_idboolean/nullfalseThe Claude Code shim adds --session-id <uuid> to a fresh interactive claude launch, so Paneflow knows the conversation before any hook arrives. Read by panes started after the change.

usage

KeyTypeDefaultNotes
usage.plan_limitsboolean/nulltruePaneflow installs its status line relay, paneflow-ai-hook StatusLine, in each Claude Code config directory whose settings.json has no statusLine, so the plan limits Claude Code hands its status line reach Paneflow. A status line of your own is never changed. false removes the relay at the next integration refresh. No credential is read.
usage.sidebar_agentsarray/nullnullThe agents whose plan limits the sidebar capsule and its bubble show, by runtime slug: claude-code, codex. null shows every agent, and an empty list hides the capsule. Settings › Usage always lists every account. Set from Settings › Usage › Sidebar.

worktrees

Paneflow creates a git worktree when you open a branch from the "New pane" palette, a tab's context menu, or paneflow up. Nothing is written inside the checkout: the ownership marker lives in the worktree's own git dir (.git/worktrees/<name>/ in the main repository), so git status stays clean and the marker disappears with the worktree. Settings > Worktrees edits the same keys and lists the worktrees Paneflow manages.

Leaving the branch name empty in the palette creates a detached checkout at the chosen base, named <base>-<sha7>; "Create branch here…" in the tab's context menu turns it into a branch later, keeping any uncommitted changes.

A .worktreeinclude file at the repository root lists the git-ignored files and directories to copy into every new worktree, one path per line relative to the root, # for comments, trailing / optional for directories. Without the file, Paneflow copies the top-level .env* files and AGENTS.override.md when they exist. A file that already exists in the worktree is never overwritten.

Before a managed worktree is removed, automatically or by hand, its uncommitted changes are saved as a snapshot commit under refs/paneflow/snapshots/ in the main repository: tracked edits, new files, and the branch it was on. Settings > Worktrees lists the snapshots; Restore recreates the worktree with those changes uncommitted on the same branch, Delete drops the ref. A clean worktree leaves no snapshot.

KeyTypeDefaultNotes
worktrees.dirstring/null~/.paneflow/worktreesRoot directory for managed worktrees. Each repository gets a subdirectory named <repo>-<hash>, each branch a directory under it. The default is ~/.paneflow/worktrees on every platform (%USERPROFILE%\.paneflow\worktrees on Windows). ~ expands to the home directory. Worktrees created under an earlier root, including the old <repo>.worktrees/ sibling, keep working where they are.
worktrees.auto_removeboolean/nulltrueRemove a managed worktree when its workspace closes, and trim the oldest managed worktrees past keep_limit. Uncommitted changes are saved as a snapshot first, and the branch is never deleted. false keeps every worktree until you remove it from Settings > Worktrees or the tab menu.
worktrees.keep_limitinteger/null15Number of managed worktrees to keep before the oldest ones that no open tab uses are removed. 0 to 200.
worktrees.for_new_branchesboolean/nulltrueDefault state of the Worktree toggle in the New branch form. true creates a worktree for the branch; false switches the workspace checkout to it instead, and the pane opens at the repository root. The toggle rewrites this key, and the switch is refused while an agent is working in that checkout.
{
  "worktrees": {
    "dir": "~/worktrees",
    "auto_remove": true,
    "keep_limit": 15
  }
}

agent_profiles

agent_profiles is a list. Each entry adds a launcher item that runs one of the built-in agents with extra environment variables and arguments. Profiles show up in the pane palette next to the built-in agents, and keep the base agent's status tracking, hooks, and sessions. Settings > Agents > Profiles edits the same list.

KeyTypeDefaultNotes
agent_profiles.*.namestringrequiredLabel shown in the launcher.
agent_profiles.*.agentstringrequiredTag of the base agent: claude_code, codex, opencode, pi, hermes, grok, amp, gemini, copilot, factory, or openclaw.
agent_profiles.*.envobject{}Environment variables set on the agent process. A leading ~ expands to the home directory, and $NAME, ${NAME} or %NAME% anywhere in a value takes that variable from Paneflow's own environment. A $ or % that names nothing stays literal; a name the environment does not define is refused by the Settings editor and, in a hand-written config, leaves the whole value untouched with a warning in the log.
agent_profiles.*.argsstring array[]Extra arguments appended after the base agent's own flags. Each token must be a plain word: letters, digits, -, _, ., =.

An entry with an unknown agent tag, a blank name, or an unsafe token is skipped with a warning; the other profiles still load.

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

spaces

spaces is a list of named groups of workspaces, like spaces in Arc. Each workspace belongs to one space, and the sidebar and Cmd/Ctrl+1 to Cmd/Ctrl+9 only cover the workspaces of the active space. A workspace with no space belongs to the implicit space named Default. With no spaces entry, nothing changes. Which space holds each workspace, and which space is active, are kept in session.json, not here.

KeyTypeDefaultNotes
spaces.*.idstringrequiredLowercase hyphenated UUID that session.json uses to refer to the space. Keep it when you rename the space.
spaces.*.namestringrequiredName shown for the space, 1 to 32 characters after trimming, unique ignoring case. Default is reserved.
spaces.*.colorstringnonered, green, yellow, blue, magenta, or cyan: the gradient family drawn in the space's circle when it has no image, the same in every theme. Any other value leaves the space without a color.
spaces.*.avatarstringnoneFile name of the space's image in avatars/ under the Paneflow home, a 96 pixel square PNG written by Settings > Spaces. The image replaces the color's gradient in the sidebar and in Settings. A value that does not match ^[A-Za-z0-9][A-Za-z0-9.-]{0,91}\.png$ is ignored with a warning in the log.
spaces.*.envobject{}Variables set on every terminal of the space's workspaces opened after the change. Precedence, lowest first: terminal.env, spaces.*.env, agent_profiles.*.env, the surface's env. ~/ expands to the home directory and $NAME to Paneflow's environment.

An entry with a missing or malformed id, an id already used, an empty, duplicate, reserved, or too long name, or any entry after the ninth valid one, is skipped with a warning in the log; the other spaces still load. A spaces value that is not an array loads as an empty list. When an edit removes a space while Paneflow runs, its workspaces move to Default, which becomes the active space if the removed one was.

A key in env that is not a variable name, starts with PANEFLOW_, is one Paneflow sets for every terminal (TERM, COLORTERM, TERM_PROGRAM, TERM_PROGRAM_VERSION, SHLVL, ZDOTDIR), or changes how programs load or run agents (LD_*, DYLD_*, inherited agent session markers such as CLAUDECODE) is ignored with a warning in the log, as is a non-string value. CLAUDE_CONFIG_DIR, CODEX_HOME, and GH_CONFIG_DIR must be absolute after expansion, or they are ignored the same way; Paneflow creates a missing one, mode 0700 on Linux and macOS, before a terminal of the space starts. A $NAME that names a variable Paneflow's environment does not set leaves the value unexpanded, with a warning in the log. On Windows, terminals and subprocesses receive the names upper-cased; paneflow.json keeps the case you typed.

Paneflow's own subprocesses for a workspace of the space (the pull request badge's gh, git, cloning while the space is active, and the claude -p or codex exec that names tabs) receive only these variables of the space: GIT_AUTHOR_NAME, GIT_AUTHOR_EMAIL, GIT_COMMITTER_NAME, GIT_COMMITTER_EMAIL, GIT_CONFIG_GLOBAL, GIT_SSH_COMMAND, SSH_AUTH_SOCK, GH_CONFIG_DIR, GH_TOKEN, GITHUB_TOKEN, CLAUDE_CONFIG_DIR, CODEX_HOME, ANTHROPIC_API_KEY, and OPENAI_API_KEY. Git picks the space of the workspace whose folder, repository or worktree most closely contains the directory it runs in. The tab-naming Codex process keeps its own short list of variables. A workspace of Default runs these processes with Paneflow's environment, unchanged.

gh gives GH_TOKEN and GITHUB_TOKEN precedence over the accounts stored in GH_CONFIG_DIR, and Claude Code gives ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN, and CLAUDE_CODE_OAUTH_TOKEN precedence over the login stored in CLAUDE_CONFIG_DIR, so a space that relies on a config directory should redefine any of these that Paneflow's environment exports. A git push over HTTPS follows GH_CONFIG_DIR only when git's credential helper is gh auth git-credential; over SSH, set GIT_SSH_COMMAND instead. Values are stored in plain text: prefer a config directory over a token.

{
  "spaces": [
    {
      "id": "3f1c2d4e-5a6b-4c7d-8e9f-0a1b2c3d4e5f",
      "name": "Work",
      "env": {
        "CLAUDE_CONFIG_DIR": "~/.claude-work",
        "CODEX_HOME": "~/.codex-work",
        "GH_CONFIG_DIR": "~/.config/gh-work",
        "GIT_AUTHOR_EMAIL": "me@work.example",
        "GIT_COMMITTER_EMAIL": "me@work.example"
      }
    }
  ]
}
{
  "spaces": [
    { "id": "3f1c2d4e-5a6b-4c7d-8e9f-0a1b2c3d4e5f", "name": "Work", "color": "blue" },
    { "id": "9b8a7c6d-5e4f-4a3b-9c2d-1e0f9a8b7c6d", "name": "Personal" }
  ]
}

commands

commands entries back both simple shell commands and Settings > Workspaces templates. A command entry must have name; workspace and command are mutually exclusive.

KeyTypeDefaultNotes
commands[].namestringrequiredDisplay name. Must not be blank.
commands[].descriptionstring/nullnoneHuman-readable description.
commands[].keywordsstring array[]Fuzzy-search keywords.
commands[].workspaceobject/nullnoneWorkspace template.
commands[].commandstring/nullnoneSimple shell command string.

Workspace template keys:

KeyTypeDefaultNotes
commands[].workspace.namestring/nullcommand nameWorkspace display name.
commands[].workspace.cwdstring/nullcurrent cwdDefault workspace directory.
commands[].workspace.layout_presetstring/nullnoneeven_h, even_v, main_vertical, or tiled.
commands[].workspace.colorstring/nullnoneSix-digit hex accent color, no leading #.
commands[].workspace.layoutobject/nullpreset layoutLayout tree root.

Layout keys:

KeyTypeNotes
commands[].workspace.layout.typestringpane or split.
commands[].workspace.layout.surfacesarrayRequired for pane nodes.
commands[].workspace.layout.directionstringRequired for split: horizontal or vertical.
commands[].workspace.layout.rationumber/nullLegacy binary split ratio, range 0.1 to 0.9. Ignored when ratios exists.
commands[].workspace.layout.ratiosnumber array/nullPer-child ratios for N-ary layouts. Must match child count and sum near 1.0.
commands[].workspace.layout.childrenarrayRequired for split; minimum two layout nodes.

Surface keys inside a pane:

KeyTypeDefaultNotes
commands[].workspace.layout.surfaces[].surface_typestring/nullterminalCurrently only terminal surfaces render.
commands[].workspace.layout.surfaces[].namestring/nullderivedSurface tab name.
commands[].workspace.layout.surfaces[].custom_namestring/nullnoneUser-assigned name that survives restart.
commands[].workspace.layout.surfaces[].commandstring/nullshellCommand to run when the surface is created.
commands[].workspace.layout.surfaces[].promptstring/nullnonePrompt to prefill after launching an agent command.
commands[].workspace.layout.surfaces[].cwdstring/nullworkspace cwdPer-surface working directory. Relative paths resolve against workspace cwd.
commands[].workspace.layout.surfaces[].pathstring/nullnoneFile opened by a markdown surface. Ignored by terminal surfaces.
commands[].workspace.layout.surfaces[].envobject/nullnoneExtra environment variables. Wins over terminal.env on collision.
commands[].workspace.layout.surfaces[].focusboolean/nullfalseGives this surface initial focus.
commands[].workspace.layout.surfaces[].scrollbackstring/nullnoneSaved plain-text scrollback restored with the surface.
commands[].workspace.layout.surfaces[].agentstring/nullnoneStable tag of the agent CLI last detected in the surface.
commands[].workspace.layout.surfaces[].font_sizenumber/nullglobal font_sizePer-surface font-size override, range 8.0 to 32.0.
commands[].workspace.layout.surfaces[].sessionstring/nullnoneUUID of the persistent host session the terminal reattaches to on restore. Written by Paneflow.
commands[].workspace.layout.surfaces[].agent_sessionobject/nullnoneAgent conversation last started in the surface: runtime (catalog id), id (provider session id), and cwd. Paneflow reopens it when the host session did not survive. Written by Paneflow.

telemetry

KeyTypeDefaultNotes
telemetry.enabledboolean/nullnullnull means unanswered, true means opted in, false means opted out.

Complete example

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