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
| Page | What it controls | Writes to | Applies |
|---|---|---|---|
| General | Default external editor and default shell for new terminal panes. | external_editor, default_shell | New launches. Running terminals keep their current process. |
| Appearance | Light, 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_material | Theme, density, style, icon, and material changes hot-reload. |
| Keyboard Shortcuts | Action bindings and reset to defaults. | shortcuts | Reloaded after the config save. |
| Notifications | Native OS notifications for waiting agents and for notifications sent by terminal programs. | agent_panel.notify_when_agent_waiting | Hot-reloads. |
| Terminal | Cursor 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_material | Display controls hot-reload. Cursor shape applies to the next new terminal. |
| Workspaces | Reusable workspace templates with panes, agents, shell commands, cwd, env, and prompt prefill. | commands[].workspace | Templates run through the same workspace launch path as paneflow up. |
| Spaces | The 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 home | Names, images, and colors hot-reload. An environment applies to terminals opened after the change. |
| Worktrees | Root 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_limit | Hot-reloads. The root applies to worktrees created from then on. |
| Agents | Which 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 config | Launcher and access changes hot-reload. |
| Plugins | Installs or repairs the bundled paneflow-mcp bridge for Claude Code, Codex, Gemini, and opencode. | Agent config files, not paneflow.json | Re-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.
| Style | What 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. |
| Rounded | The 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.
| Style | Windows | macOS | Linux |
|---|---|---|---|
| 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. |
| Blended | Both 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.
| Icon | What it draws |
|---|---|
| Glass (default) | The installed icon: three glass panes on a violet tile. |
| Black | The Paneflow mark in off-white horizontal bars on a black tile. |
| White | The same bars in dark ink on a white tile. |
| Black solid | The three panes as solid off-white shapes on a black tile. |
| White solid | The same solid panes in dark ink on a white tile. |
Sixteen illustrated icons follow. Each one shows the same mark in another material.
| Icon | app_icon | What it draws |
|---|---|---|
| Aubergine | aubergine | Lilac panes on a deep aubergine tile. |
| Paper | paper | Panes in aubergine ink on an off-white paper tile. |
| Midnight matte | midnight-matte | Dark gray panes on a matte black tile. |
| Polar | polar | Blue and cyan panes on an ice-white tile. |
| Melon | melon | Coral and orange panes on a cream tile. |
| Honeydew | honeydew | Dark green panes on a mint and lime tile. |
| Berry | berry | Plum panes on a violet and pink tile. |
| Rainbow | rainbow | Panes in six retro stripes on a black tile. |
| Solarwave | solarwave | Chrome sunset bands on a deep purple tile. |
| Neon | neon | Cyan and pink neon outlines on a dark violet tile. |
| Phosphor | phosphor | Glowing green panes on a black screen tile. |
| Holo | holo | Dark panes on an iridescent foil tile. |
| Amethyst | amethyst | Lilac panes on a faceted violet gem. |
| Blueprint | blueprint | Pale blue panes on a blueprint tile. |
| Chip | chip | Brushed metal panes on a chip, set in a green circuit board. |
| Nostalgia | nostalgia | Chrome-white panes on a glossy blue tile. |
| Platform | Where the choice shows | When |
|---|---|---|
| Windows | The 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. |
| macOS | The Dock and the app switcher, while Paneflow runs. | At once. |
| Linux, X11 | The window icon the window manager and the task switcher read. | Windows opened after the change; restart Paneflow to apply it to all. |
| Linux, Wayland | Nowhere: 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 value | terminal.minimum_contrast | Effect |
|---|---|---|
| Auto | key absent | APCA Lc 60 on every theme, light and dark. |
| Off | 0 | No correction. Programs keep the colors they asked for. |
| 45, 60, 75, 90 | that number | An 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.
| Field | What it does |
|---|---|
| Name | Click 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. |
| Image | Upload 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. |
| Color | No 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. |
| Environment | A summary of the space's variables and an Edit button. See Space environment. |
| Agent setup | Shown 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_linesfor per-terminal scrollback history.terminal.ligatures,terminal.cursor_blink,terminal.env, andterminal.scroll_multiplierfor advanced terminal behavior. Every Paneflow build emulates its panes with one pinned, statically linkedlibghostty-vtengine, 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
shortcutsoverrides. - Themes - bundled theme names and hot-reload behavior.