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
| Platform | 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.
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
| Key | Type | Default | Applied | Notes |
|---|---|---|---|---|
$schema | string | none | Editor only | Points editors to the published schema. Ignored by Paneflow. |
$schemaVersion | string | 1.0.0 | Startup/reload | Unknown versions warn but do not block loading. |
default_shell | string/null | Platform shell fallback | New terminal | Unix: configured -> $SHELL -> /bin/sh. Windows: configured -> pwsh.exe -> powershell.exe -> %ComSpec% -> C:\Windows\System32\cmd.exe -> cmd.exe. |
theme | string/null | Paneflow Dark | Hot reload | The 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_mode | string/null | dark | Hot reload | light and dark force the matching bundled theme; system follows the OS window appearance. |
font_family | string/null | bundled JetBrainsMono Nerd Font | Hot reload cache | Accepts .PaneflowMono, JetBrainsMono NF, JetBrainsMono NFM, .PaneflowSans, embedded font names, or installed monospace families. |
font_fallbacks | string array/null | GPUI fallback stack | Hot reload cache | Ordered extra fallback families for glyphs missing from font_family. |
font_size | number/null | 13.0 | Hot reload cache | Points, valid range 8.0 to 32.0; invalid values fall back to 13.0. |
font_weight | string/null | normal | Hot reload cache | One of thin, extra_light, light, semi_light, normal, medium, semi_bold, bold, extra_bold, black, extra_black. |
line_height | number/null | 1.0 | Hot reload cache | Multiplier 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_width | number/null | 1.0 | Hot reload cache | Multiplier of the font's advance, valid range 0.8 to 2.0. The cell is rounded to whole device pixels. |
unfocused_pane_opacity | number/null | 1.0 | Hot reload | Opacity 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_motion | boolean/null | false | Hot reload | Minimizes 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_density | boolean/null | true | Hot reload | Separates 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_style | string/null | classic | Hot reload | Layout 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_icon | string/null | default | Hot reload | Glyph 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_icon | string/null | glass | Hot reload on Windows and macOS; new windows on Linux X11 | Icon 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_show | object/null | status, shimmer, agents, agent_logo, agent_workspace, and agent_shimmer on, others off | Hot reload | What 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_by | string/null | folder | Hot reload | How 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. |
worktrees | object/null | see below | Hot reload | Where 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_decorations | string/null | client | Startup | client draws Paneflow chrome; server delegates to the OS compositor. |
window_backdrop | string/null | auto | Startup | auto, 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_material | boolean/null | false | Window/terminal render | Windows-only terminal background material toggle. The Mica and Blended background styles set it to true, Themed to false. Ignored on other platforms. |
windows_chrome_material | boolean/null | false | Window/chrome render | Windows-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_veil | boolean/null | false | Window/chrome render | Windows-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_material | boolean/null | false | Window/chrome render | macOS-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_material | boolean/null | false | Window/terminal render | Linux-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_material | boolean/null | false | Window/chrome render | Linux-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_meta | boolean/null | true on Linux and Windows, false on macOS | Hot reload | Sends 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_integration | boolean/null | true | New terminal | Enables Paneflow shell snippets for OSC 7 CWD and OSC 133 command marks. |
editor | object/null | defaults below | Hot reload | How the code editor and the dock's file viewers show a file: minimap, scrollbar, word_wrap, markdown_rendered, and csv_table. See editor. |
automation | object/null | all off | Hot reload | Background 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_ms | integer/null | 70 | IPC send | Floor delay between bracketed paste and Enter for paneflow send --submit. Range 10 to 5000. |
external_editor | string/null | auto | Next open action | Editor 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. |
shortcuts | object | {} | Hot reload | Maps keystrokes to action names. See shortcuts and actions. |
terminal | object/null | defaults below | Mixed | Namespaced terminal renderer and PTY settings. |
commands | array | [] | Settings/Run | Command palette entries and workspace templates. |
agent_profiles | array | [] | Hot reload | Custom 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. |
spaces | array | [] | Hot reload | Named groups of workspaces, at most 9. The sidebar lists only the active space's workspaces. See spaces. |
claude_code_bypass_permissions | boolean/null | false | Next Claude launch | Adds --permission-mode bypassPermissions to the Claude Code launcher. High-risk opt-in. |
ai_unrestricted | boolean/null | false | Per IPC call | Allows trusted conductors to submit to peer panes without PANEFLOW_IPC_SCRIPTING. |
ai_injection_fence | boolean/null | true | Per read call | Wraps surface.read output in an untrusted-output fence by default. |
on_quit | ask, keep, stop, null | ask | At quit | What 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_panel | object/null | defaults below | Agents UI | Agents-view notification preferences. |
agents | object/null | defaults below | Restore and next launch | Agent conversation restore and Claude Code session-id preassignment. |
usage | object/null | defaults below | Next integration refresh | Subscription usage: whether Paneflow relays Claude Code plan limits. |
telemetry | object/null | { "enabled": null } | Startup/consent | Desktop 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.
| Key | Agent |
|---|---|
claude_code_button_visible | Claude Code |
codex_button_visible | Codex |
opencode_button_visible | OpenCode |
pi_button_visible | Pi |
hermes_agent_button_visible | Hermes Agent |
grok_button_visible | Grok |
amp_button_visible | Amp |
gemini_button_visible | Gemini |
copilot_button_visible | Copilot |
factory_button_visible | Factory |
openclaw_button_visible | OpenClaw |
muse_button_visible | Muse Code |
fx_button_visible | fx (Linux and macOS) |
terminal
| Key | Type | Default | Applied | Notes |
|---|---|---|---|---|
terminal.ligatures | boolean/null | true | Hot reload cache | Enables programming ligatures when the active font supports them. |
terminal.integrated_glyphs | boolean/null | true | Hot reload | Draws built-in block glyphs as filled quads. |
terminal.color_emoji | boolean/null | true | Hot reload | Uses the platform color-emoji path. |
terminal.cursor_color | string/null | theme cursor | Hot reload/new terminal | #RRGGBB, RRGGBB, #RGB, or RGB. |
terminal.scrollbar | boolean/null | true | New terminal view | Overlay scrollbar shown while scrolling or hovering the right edge of a pane. |
terminal.scrollback_lines | integer/null | 10000 | New terminal | Range 100 to 100000. Cached terminals cap at 1000. |
terminal.cursor_shape | string/null | block | New terminal | vintage, block, beam, underline, double_underline, or hollow. |
terminal.osc52_clipboard | string/null | copy | New terminal view | Available 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_in | string/null | dock | Immediate | Available 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_report | boolean/null | false | New session | Available 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_extension | integer/null | 0 | New session | Available 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_blink | string/null | terminal_controlled | New terminal | on, off, or terminal_controlled. |
terminal.env | object/null | none | New terminal | Environment 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_multiplier | number/null | 1.0 | New terminal view | Range 0.1 to 10.0. Ignored in mouse-reporting and alternate-screen scroll paths. |
terminal.minimum_contrast | number/null | Auto (60) | Hot reload | Minimum 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
| Key | Type | Default | Applied | Notes |
|---|---|---|---|---|
editor.minimap | boolean/null | false | Hot reload | Draws 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.scrollbar | boolean/null | true | Hot reload | Draws the editor's vertical scrollbar. Toggled from the editor's controls menu; the choice applies to every open file. |
editor.word_wrap | boolean/null | false | Next file open | Wraps 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_rendered | boolean/null | false | Hot reload | Shows 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_table | boolean/null | true | Hot reload | Shows .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
| Key | Type | Default | Notes |
|---|---|---|---|
agent_panel.notify_when_agent_waiting | string/null | Never | PrimaryScreen, AllScreens, or Never. Also governs desktop notifications that terminal programs send with OSC 9 or OSC 777. |
agents
| Key | Type | Default | Notes |
|---|---|---|---|
agents.restore_conversations | boolean/null | true | When 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_methods | object | {} | 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_id | boolean/null | false | The 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
| Key | Type | Default | Notes |
|---|---|---|---|
usage.plan_limits | boolean/null | true | Paneflow 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_agents | array/null | null | The 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.
| Key | Type | Default | Notes |
|---|---|---|---|
worktrees.dir | string/null | ~/.paneflow/worktrees | Root 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_remove | boolean/null | true | Remove 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_limit | integer/null | 15 | Number of managed worktrees to keep before the oldest ones that no open tab uses are removed. 0 to 200. |
worktrees.for_new_branches | boolean/null | true | Default 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.
| Key | Type | Default | Notes |
|---|---|---|---|
agent_profiles.*.name | string | required | Label shown in the launcher. |
agent_profiles.*.agent | string | required | Tag of the base agent: claude_code, codex, opencode, pi, hermes, grok, amp, gemini, copilot, factory, or openclaw. |
agent_profiles.*.env | object | {} | 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.*.args | string 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.
| Key | Type | Default | Notes |
|---|---|---|---|
spaces.*.id | string | required | Lowercase hyphenated UUID that session.json uses to refer to the space. Keep it when you rename the space. |
spaces.*.name | string | required | Name shown for the space, 1 to 32 characters after trimming, unique ignoring case. Default is reserved. |
spaces.*.color | string | none | red, 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.*.avatar | string | none | File 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.*.env | object | {} | 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.
| Key | Type | Default | Notes |
|---|---|---|---|
commands[].name | string | required | Display name. Must not be blank. |
commands[].description | string/null | none | Human-readable description. |
commands[].keywords | string array | [] | Fuzzy-search keywords. |
commands[].workspace | object/null | none | Workspace template. |
commands[].command | string/null | none | Simple shell command string. |
Workspace template keys:
| Key | Type | Default | Notes |
|---|---|---|---|
commands[].workspace.name | string/null | command name | Workspace display name. |
commands[].workspace.cwd | string/null | current cwd | Default workspace directory. |
commands[].workspace.layout_preset | string/null | none | even_h, even_v, main_vertical, or tiled. |
commands[].workspace.color | string/null | none | Six-digit hex accent color, no leading #. |
commands[].workspace.layout | object/null | preset layout | Layout tree root. |
Layout keys:
| Key | Type | Notes |
|---|---|---|
commands[].workspace.layout.type | string | pane or split. |
commands[].workspace.layout.surfaces | array | Required for pane nodes. |
commands[].workspace.layout.direction | string | Required for split: horizontal or vertical. |
commands[].workspace.layout.ratio | number/null | Legacy binary split ratio, range 0.1 to 0.9. Ignored when ratios exists. |
commands[].workspace.layout.ratios | number array/null | Per-child ratios for N-ary layouts. Must match child count and sum near 1.0. |
commands[].workspace.layout.children | array | Required for split; minimum two layout nodes. |
Surface keys inside a pane:
| Key | Type | Default | Notes |
|---|---|---|---|
commands[].workspace.layout.surfaces[].surface_type | string/null | terminal | Currently only terminal surfaces render. |
commands[].workspace.layout.surfaces[].name | string/null | derived | Surface tab name. |
commands[].workspace.layout.surfaces[].custom_name | string/null | none | User-assigned name that survives restart. |
commands[].workspace.layout.surfaces[].command | string/null | shell | Command to run when the surface is created. |
commands[].workspace.layout.surfaces[].prompt | string/null | none | Prompt to prefill after launching an agent command. |
commands[].workspace.layout.surfaces[].cwd | string/null | workspace cwd | Per-surface working directory. Relative paths resolve against workspace cwd. |
commands[].workspace.layout.surfaces[].path | string/null | none | File opened by a markdown surface. Ignored by terminal surfaces. |
commands[].workspace.layout.surfaces[].env | object/null | none | Extra environment variables. Wins over terminal.env on collision. |
commands[].workspace.layout.surfaces[].focus | boolean/null | false | Gives this surface initial focus. |
commands[].workspace.layout.surfaces[].scrollback | string/null | none | Saved plain-text scrollback restored with the surface. |
commands[].workspace.layout.surfaces[].agent | string/null | none | Stable tag of the agent CLI last detected in the surface. |
commands[].workspace.layout.surfaces[].font_size | number/null | global font_size | Per-surface font-size override, range 8.0 to 32.0. |
commands[].workspace.layout.surfaces[].session | string/null | none | UUID of the persistent host session the terminal reattaches to on restore. Written by Paneflow. |
commands[].workspace.layout.surfaces[].agent_session | object/null | none | Agent 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
| Key | Type | Default | Notes |
|---|---|---|---|
telemetry.enabled | boolean/null | null | null means unanswered, true means opted in, false means opted out. |
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"
}
]
}
}
}
]
}