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. |
| Themes | Light, Dark, System, plus dedicated Windows and macOS sidebar-material controls when available. | theme, windows_chrome_material, macos_chrome_material | Theme 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. | 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 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 | 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. |
| 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, 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 | 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. |
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.