Skip to content
PaneflowPaneflow

Settings

Understand what Paneflow's Settings panel controls, what it writes to paneflow.json, and which advanced keys stay config-only.

Paneflow's Settings panel is the human UI for common preferences. It is not the full configuration reference. Use it for the settings you adjust often: editor, shell, theme, shortcuts, notifications, terminal display, workspace templates, agent launchers, AI access, and MCP setup.

TL;DR. Most Settings rows write to paneflow.json and hot-reload after the file is saved. Plugins is different: it installs or repairs Paneflow's MCP bridge in supported agent configs. Advanced keys remain available in paneflow.json.

Settings map

PageWhat it controlsWrites toApplies
GeneralDefault external editor and default shell for new terminal panes.external_editor, default_shellNew launches. Running terminals keep their current process.
AppearanceLight, Dark, System, the theme preset, Comfortable density, Interface style, Workspace icon, Background style on Windows, macOS, and Linux, App icon, plus dedicated Windows, macOS, and Linux sidebar-material controls.theme, comfortable_density, interface_style, workspace_icon, app_icon, windows_chrome_material, windows_terminal_material, macos_chrome_material, linux_chrome_material, linux_terminal_materialTheme, density, style, icon, and material changes hot-reload.
Keyboard ShortcutsAction bindings and reset to defaults.shortcutsReloaded after the config save.
NotificationsNative OS notifications for waiting agents and for notifications sent by terminal programs.agent_panel.notify_when_agent_waitingHot-reloads.
TerminalCursor shape and color, font family, font size, font weight, line height, cell width, integrated glyphs, color emoji, minimum contrast, and Windows and Linux terminal material.terminal.cursor_shape, terminal.cursor_color, font_family, font_size, font_weight, line_height, cell_width, terminal.integrated_glyphs, terminal.color_emoji, terminal.minimum_contrast, windows_terminal_material, linux_terminal_materialDisplay controls hot-reload. Cursor shape applies to the next new terminal.
WorkspacesReusable workspace templates with panes, agents, shell commands, cwd, env, and prompt prefill.commands[].workspaceTemplates run through the same workspace launch path as paneflow up.
SpacesThe spaces that group workspaces: Default first, then each space with its name, image, color, environment variables, the state of the Claude Code and Codex hooks and MCP in the config directories it sets, and a delete action that moves its workspaces to Default after a confirmation. Up to 9 spaces.spaces; images go to avatars/ in the Paneflow homeNames, images, and colors hot-reload. An environment applies to terminals opened after the change.
WorktreesRoot directory for the worktrees Paneflow creates, automatic removal with a keep limit, the list of managed worktrees with a remove action, and the snapshots taken before a removal with restore and delete actions.worktrees.dir, worktrees.auto_remove, worktrees.keep_limitHot-reloads. The root applies to worktrees created from then on.
AgentsWhich agents the launcher shows, with their installed version and hook state, a Paneflow hooks toggle for Claude Code and Codex, custom agent profiles, Claude Code full access, AI free access, and the injection fence.*_button_visible, agent_profiles, claude_code_bypass_permissions, ai_unrestricted, ai_injection_fence; the Paneflow hooks toggle writes the agent's own hook configLauncher and access changes hot-reload.
PluginsInstalls or repairs the bundled paneflow-mcp bridge for Claude Code, Codex, Gemini, and opencode.Agent config files, not paneflow.jsonRe-run after a Paneflow update or when an agent config changes.

Interface style

Settings > Appearance offers Interface style under the theme preset, and the command palette carries the same choice under Interface style. It chooses the layout and the corner language of the whole app and is stored in interface_style.

StyleWhat it draws
Classic (default)An edge-to-edge window: the sidebar, the panes, and the Changes dock run to the window edges with thin lines between them, the tabs of the top panes and of the dock sit in the title bar beside the window controls, and the empty part of that row drags the window. Circular corners on a tight scale: 12 px dialogs and toasts, and 8 px rows, buttons, and pane tabs. Comfortable density has no effect.
RoundedThe look of Paneflow 0.19 and earlier: pane cards with continuous corners (squircles) and generous radii, floating under a full-width title bar. Comfortable density applies to this style only.

In both styles, every menu and select popup is an 8 px panel with 28 px rows, 14 px labels, and 12 px shortcuts. The command palette and the Clone repository dialog look the same in both styles. The change applies at once to every open window. Paneflow opens in Classic from 0.20.0 on; to keep the floating pane cards, pick Rounded or set "interface_style": "rounded".

Background style

On Windows, macOS, and Linux, Settings > Appearance offers Background style under the interface style, and the command palette carries the same choice under Background style. It sets every window material of the platform at once. Up to 0.19 this setting was named Interface style; it keeps its values and its keys.

StyleWindowsmacOSLinux
Themed (default)windows_chrome_material and windows_terminal_material set to false: solid theme colors.macos_chrome_material set to false: an opaque sidebar.linux_chrome_material and linux_terminal_material set to false: an opaque window.
BlendedBoth set to true: Mica shows through the sidebar and the terminal.macos_chrome_material set to true: the native Sidebar material shows behind the sidebar.Both set to true: the desktop shows through a veil behind the sidebar and a denser one behind the terminal.

On Linux, with "window_backdrop": "blurred", Paneflow asks a Wayland compositor that offers ext-background-effect or KDE's blur to blur what lies behind the translucent window, following its rounded corners. Elsewhere, including X11 and GNOME, Paneflow requests no blur: the compositor may supply one, for example the Blur my Shell extension on GNOME. Without one, the wallpaper shows through the veil unblurred.

There is no background_style key: Paneflow reads the style back from those switches. When they disagree, for example after turning one of them on by hand, the row reads Custom.

Workspace icon

Settings > Appearance offers Workspace icon, and the command palette carries the same choice under Workspace icon. It chooses the glyph in front of each workspace in the sidebar and is stored in workspace_icon. Default keeps Paneflow's outlined folder. Standard drops the folder for a disclosure chevron, right when the workspace is folded and down when it is open. Metal is a filled glass folder, Windows a yellow gradient folder, Windows 95 the 16-color pixel folder, and Pixel an outlined pixel folder. Every style has a closed and an open glyph, and the two pixel styles are sharpest at a display scale of 100 % or 200 %.

App icon

Settings > Appearance offers App icon at the bottom of the theme card. It chooses the icon Paneflow shows for its running windows and is stored in app_icon. The row shows the current icon and its name; click it to unfold a gallery of every icon, and pick one to apply it at once.

IconWhat it draws
Glass (default)The installed icon: three glass panes on a violet tile.
BlackThe Paneflow mark in off-white horizontal bars on a black tile.
WhiteThe same bars in dark ink on a white tile.
Black solidThe three panes as solid off-white shapes on a black tile.
White solidThe same solid panes in dark ink on a white tile.

Sixteen illustrated icons follow. Each one shows the same mark in another material.

Iconapp_iconWhat it draws
AubergineaubergineLilac panes on a deep aubergine tile.
PaperpaperPanes in aubergine ink on an off-white paper tile.
Midnight mattemidnight-matteDark gray panes on a matte black tile.
PolarpolarBlue and cyan panes on an ice-white tile.
MelonmelonCoral and orange panes on a cream tile.
HoneydewhoneydewDark green panes on a mint and lime tile.
BerryberryPlum panes on a violet and pink tile.
RainbowrainbowPanes in six retro stripes on a black tile.
SolarwavesolarwaveChrome sunset bands on a deep purple tile.
NeonneonCyan and pink neon outlines on a dark violet tile.
PhosphorphosphorGlowing green panes on a black screen tile.
HoloholoDark panes on an iridescent foil tile.
AmethystamethystLilac panes on a faceted violet gem.
BlueprintblueprintPale blue panes on a blueprint tile.
ChipchipBrushed metal panes on a chip, set in a green circuit board.
NostalgianostalgiaChrome-white panes on a glossy blue tile.
PlatformWhere the choice showsWhen
WindowsThe taskbar button, Alt+Tab, and the shortcuts in your profile that open this Paneflow: the one pinned to the taskbar, a desktop shortcut, the Start menu entry.Alt+Tab at once. The taskbar button at the next sign-in or restart of Windows Explorer. A shortcut keeps the icon while Paneflow is closed.
macOSThe Dock and the app switcher, while Paneflow runs.At once.
Linux, X11The window icon the window manager and the task switcher read.Windows opened after the change; restart Paneflow to apply it to all.
Linux, WaylandNowhere: the compositor takes the icon from the installed desktop entry.Never.

On Windows a pinned taskbar button shows the icon of its shortcut, not of the window, so Paneflow points that shortcut at an icon file it writes under icons/ in the Paneflow home, and checks it again at each launch. Windows caches the image of a taskbar button and reads the shortcut again only when it reloads the taskbar, so the button changes at the next sign-in, or once Windows Explorer restarts. Choosing Glass restores the shortcut's own icon.

The Start menu shortcut of a machine-wide install is not yours to modify. For any icon other than Glass, Paneflow copies it to the same place in your own Start menu folder, which Windows prefers, and gives that copy the icon; choosing Glass deletes the copy. If you uninstall Paneflow while another icon is selected, the copy stays behind: delete it from %APPDATA%\Microsoft\Windows\Start Menu\Programs.

On macOS and Linux the installed launcher and the Dock tile of a Paneflow that is not running keep the Glass icon.

Terminal contrast

Paneflow raises the contrast of text a program colored itself when it lands too close to its background. Settings > Terminal exposes it as Minimum contrast, and the command palette carries the same values under Minimum contrast.

Row valueterminal.minimum_contrastEffect
Autokey absentAPCA Lc 60 on every theme, light and dark.
Off0No correction. Programs keep the colors they asked for.
45, 60, 75, 90that numberAn explicit APCA Lc target.

Values above 90 are capped at 90. Negative or invalid values fall back to Auto.

Only colors a program chose are corrected: truecolor and palette indices 16 to 255. The theme's own sixteen ANSI colors, its foreground, and its background are left unchanged. The correction first adjusts lightness while preserving hue. If it has to remove too much saturation, it moves toward the nearest theme color.

Changes hot-reload in open terminals. To turn the correction off everywhere, set "minimum_contrast": 0 under terminal in paneflow.json.

Spaces

Spaces opens with a New space button beside its introduction, then a card that lists Default first. Default holds every workspace that has no space, reads Workspaces without a space or its workspace count, and cannot be renamed or deleted. One row per space follows, with its circle, its name, and its workspace and variable counts; a collapsed row also flags Agent setup failed or its environment warnings. Click a row to expand it. Only one space is expanded at a time.

FieldWhat it does
NameClick the name to edit it, then press Enter to save or Escape to cancel; clicking elsewhere also saves. A name must be 1 to 32 characters, cannot be Default, and cannot repeat another space's name, ignoring case. An invalid name shows the reason under the field, and nothing is saved.
ImageUpload image opens a file picker, as does a click on the space's circle. Once an image is set, the buttons read Replace image and Remove image. See Space image.
ColorNo color, or one of Red, Green, Yellow, Blue, Magenta, and Cyan. A space without an image draws its color as a gradient in its circle, the same in every theme, and without a color an outline.
EnvironmentA summary of the space's variables and an Edit button. See Space environment.
Agent setupShown when the space moves CLAUDE_CONFIG_DIR or CODEX_HOME away from the default: one line per agent, such as Claude Code hooks and MCP, with its state, Retry after an error, and Install when it is not installed.

Delete space, at the bottom of an expanded space, asks Delete Work? Its 3 workspaces move to Default. with Cancel and Delete space. Confirming moves the space's workspaces to Default without closing any terminal, makes Default active if the deleted space was, and removes the space's image.

New space adds Space N with the first free number and opens its name for editing, as do New space… in the sidebar's space menu and New space in the command palette. With 9 spaces the button is disabled and 9 spaces maximum appears beside it.

Space image

An image replaces the color gradient in the space's circle, in the sidebar header, the space menu, and Settings. Choose a PNG, JPEG, WebP, GIF, BMP, or TIFF file of at most 25 MB and 12,000 pixels on each side. Paneflow applies the photo's EXIF orientation, crops it to a centered square, and stores a 96 pixel PNG in avatars/ under the Paneflow home (~/.paneflow/avatars/, %USERPROFILE%\.paneflow\avatars\ on Windows). The file name is recorded as avatar on the space's entry in paneflow.json. An image that cannot be read or is too large shows the reason under the Image field, and the space keeps its previous circle. Replacing or removing an image deletes the previous file.

Space environment

Edit under Environment opens one row per variable. The values are set on every terminal opened from then on in that space's workspaces, above terminal.env and below an agent profile's env and a surface's own env. A leading ~ is your home, and $NAME takes the value from Paneflow's environment; the line under a row shows the expanded value. Point CLAUDE_CONFIG_DIR, CODEX_HOME, or GH_CONFIG_DIR at a separate directory to use a second Claude Code, Codex, or GitHub CLI account in that space. Those three must be absolute paths; Paneflow creates a missing one, private to you on Linux and macOS, before the first terminal starts, and a toast names the directory if it cannot. Two accounts stay apart only as long as each CLI honors its directory variable, and GH_CONFIG_DIR does not isolate anything while GH_TOKEN or GITHUB_TOKEN is set.

Save refuses, with the reason under the row or the form, a value without a name, a name listed twice, a name that is not a variable name, a PANEFLOW_ name, a variable Paneflow sets for every terminal such as TERM, a variable that changes how programs load or run agents such as LD_PRELOAD or an agent session marker such as CLAUDECODE, a relative path for CLAUDE_CONFIG_DIR, CODEX_HOME, or GH_CONFIG_DIR, and a $NAME that names a variable Paneflow's environment does not set. On Windows, terminals receive the names upper-cased, while paneflow.json keeps the case you typed. A variable whose name contains KEY, TOKEN, SECRET, or PASSWORD shows Stored in plain text in paneflow.json; prefer a config directory. When Paneflow's own environment sets ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN, CLAUDE_CODE_OAUTH_TOKEN, OPENAI_API_KEY, GH_TOKEN, or GITHUB_TOKEN and the space does not redefine it, a warning says so: those variables take precedence over the account stored in a config directory.

Open terminals keep the environment they started with: moving a workspace to a space with a different environment says Open terminals keep their previous environment, and nothing restarts. A shell that exports the same variable from its rc file, for example .zshrc, overrides the space's value inside that terminal.

When a space moves CLAUDE_CONFIG_DIR or CODEX_HOME away from the default, saving it installs Paneflow's hooks and MCP bridge in that directory for each agent already installed in Settings > Agents, so the sidebar still shows when the agent works and waits. Each launch of a release build refreshes them, once per distinct pair of Claude Code and Codex directories. Agent setup lists each agent's state, with Retry after an error and Install when it is not installed.

Deleting a space leaves its hooks in place. To remove them, delete the entries marked "_paneflow_managed": true from the hooks of settings.json in the space's CLAUDE_CONFIG_DIR, the paneflow server from its .claude.json, and its skills/paneflow-conductor/SKILL.md; for Codex, delete the same entries from hooks.json and the [mcp_servers.paneflow] table from config.toml in its CODEX_HOME. The space's records live under ~/.paneflow/integrations/spaces/<space id>/ and can be deleted too.

A space organizes work; it is not a security boundary. Every terminal still runs as you, and a value in paneflow.json is readable by anything that can read your home directory.

AI access vs MCP

The Agents page controls how Paneflow launches agents and how much automation a trusted conductor can perform.

claude_code_bypass_permissions only affects Claude Code launches. When enabled, Paneflow launches Claude Code with --permission-mode bypassPermissions. It does not change Codex, OpenCode, Gemini, or MCP behavior.

Plugins is a separate operational page. It registers the bundled paneflow-mcp server so supported agents can list, read, and search Paneflow panes. It touches the agents' own config files and can be run again safely.

Config-only controls

Use paneflow.json when you need a setting that is intentionally not in the primary Settings UI.

Common examples:

  • terminal.scrollback_lines for per-terminal scrollback history.
  • terminal.ligatures, terminal.cursor_blink, terminal.env, and terminal.scroll_multiplier for advanced terminal behavior. Every Paneflow build emulates its panes with one pinned, statically linked libghostty-vt engine, so there is no engine to select.
  • commands[] entries that are not workspace templates.
  • Profiles, telemetry, window-decoration, and agent-panel options.

Paneflow reloads valid config changes through its watcher. If the JSON is malformed, the running app keeps the previous valid config instead of falling back to defaults. The JSON Schema flags unknown keys in editors; the runtime stays lenient so older builds can ignore newer keys.

See also

  • Configuration - file location, schema setup, and runtime behavior.
  • Schema - every key, type, default, and stability.
  • Shortcuts and actions - action names for shortcuts overrides.
  • Themes - bundled theme names and hot-reload behavior.