Settings
Plexus runs zero-config — every setting has a sensible default, so you only open Settings when you want to change one.
Layered settings
Settings cascade through four layers, broadest to narrowest:
Global → Workspace → Project → Session
Each layer inherits from the one above until you override the value there — a more-specific layer always wins, and if no layer sets a value the built-in default applies. So you set a default once globally, override it for a single workspace, and override it again for one project inside that workspace.
A session inherits its effective values from its owning project. Settings that govern how a session is created or started — session.autoStart, agent.skipPermissions — are decided before the session exists, so they always resolve from the project layer, never the session itself.
Settings live inside Plexus (the Settings UI, backed by Plexus's own store). There is no .plexus.toml file to edit. Repo-committed lifecycle hooks are the one exception — those live in .plexus/hooks.json; see Hooks.
The Settings UI
Open global Settings to edit defaults that apply everywhere. Rows are grouped into categories — General, Agent, Notifications, Git & PRs, Git providers, Hooks, Worktrees, Performance, Privacy, Keybindings — so you can find a setting without scrolling a flat list. Connecting GitHub or Bitbucket lives under Git providers — see Connections.
Every row shows a badge for where its current value comes from: Default, Inherited from a parent layer, or Set here. When a row is set at the layer you're viewing, a reset button (↺) appears next to its control — click it to clear the override and fall back to the inherited or default value.
Overriding at a workspace or project
Open a scope's settings from the Settings entry in its ⋯ menu (or its dashboard node). At these scopes each category carries an Override parent settings toggle:
- Off — every row is read-only and shows the value it inherits, and from where. This is the default, so a new workspace or project changes nothing.
- On — the rows become editable; anything you change is an override applied to this scope and everything inside it.
Turning the toggle back off unsets every override in that category at this layer. Some settings are global-only — the terminal shell, the agent path, diagnostics, usage analytics, and all keybindings — and don't appear on workspace or project pages, because they describe the machine, not a scope.
Theme
Switch between light, dark, and system from the title bar. The choice applies app-wide, including the Explorer editor.
Settings reference
Scope is the narrowest layer a key can be set at: Project means global → workspace → project (sessions inherit from their project); Global means per-machine only.
General
| Key | What it does | Default | Scope |
|---|---|---|---|
teardownMode | What Remove session… does: delete, archive, or prompt each time | delete | Project |
terminal.shell | Shell for the bottom terminal and in-app installers (auto, a named shell, or custom) | auto | Global |
terminal.shellPath | Full path to the shell when terminal.shell is custom | empty | Global |
diagnostics.enabled | Write a timestamped plexus-diag.log for troubleshooting (applies live) | false | Global |
Agent
| Key | What it does | Default | Scope |
|---|---|---|---|
agent.skipPermissions | Launch Claude Code with --dangerously-skip-permissions so it runs autonomously | true | Project |
agent.rewindControl | Show the Rewind control on the Agent tab (Claude Code's /rewind) | true | Project |
agent.programPath | Full path to the claude executable when it isn't on the GUI's PATH | empty | Global |
session.autoStart | Auto-launch a brand-new session's agent instead of waiting for Start | true | Project |
richInput.openByDefault | Open the multi-line compose box automatically on a running session | false | Project |
richInput.autoSend | Make Mod+Enter send the composed prompt instead of just pasting it | false | Project |
summary.enabled | Show the AI session-summary sidebar (each refresh spends a turn) | false | Project |
Notifications
| Key | What it does | Default | Scope |
|---|---|---|---|
notifications.desktop | Show a native desktop notification when a session needs you | true | Session |
notifications.sound | Play a chime when a session needs you (a preview button lets you test it) | false | Session |
Custom sound. By default the chime is synthesized in-app, but you can replace it with your own audio file under global Settings → Notifications → Custom sound (.wav, .mp3, .ogg, .flac, .m4a, and more, up to 5 MB). Plexus copies the file you pick into its own data folder, so it stays on your machine and keeps working even if you move or delete the original; Remove reverts to the built-in chime. This is a machine-wide choice (not per scope), and the per-session notifications.sound toggle still decides whether any sound plays.
On Linux, desktop notifications use notify-send — install it if alerts don't appear.
Git & PRs
| Key | What it does | Default | Scope |
|---|---|---|---|
git.pr.autoGenerateDescription | Draft the PR title and description from the diff via Claude | false | Project |
session.autoRenameOnPr | Keep a session's name in sync with its PR title (the branch keeps its slug) | true | Project |
git.teardownOnMerge | Auto-tear-down a session when its PR is detected merged (honors teardownMode) | false | Project |
git.review.prompt | Instruction Claude follows when reviewing a diff on the Review tab | senior-engineer prompt | Project |
git.commit.aiPrompt | Instruction Claude follows when drafting a commit message (the session and project Git tabs' AI button) | imperative-subject prompt | Project |
git.pull.defaultMode | The project Git client's default Pull action: fetchAll, ff, ffOnly, or rebase | ff | Project |
git.avatars.gravatar | Fetch commit-author avatars from Gravatar in the project Git client | true | Global |
git.pull.defaultMode is also settable from the Pull button's own menu — its Default action picker saves the choice for that project. git.avatars.gravatar is a per-machine privacy switch: when on, Plexus queries Gravatar with a one-way SHA-256 hash of each commit author's email (never the address itself) and caches the results on disk; turned off, no request is made at all and the graph shows locally-drawn initials instead. See the Privacy Policy.
Worktrees
| Key | What it does | Default | Scope |
|---|---|---|---|
worktree.location | Subfolder under the project root for new worktrees (session name appended) | worktrees | Project |
worktree.autoGitignore | Add the worktree parent to the repo's .gitignore when it's inside the repo | true | Project |
worktree.copyEnabled | Copy configured paths into each new worktree on create | true | Project |
worktree.copyPaths | Files/folders (relative to the project root) to copy into a new worktree | .env, .env.local | Project |
worktree.copyEnabled + worktree.copyPaths are how gitignored files like .env reach a fresh worktree. See Worktrees & environment.
Hooks
| Key | What it does | Default | Scope |
|---|---|---|---|
hooks.abortOnFailure | Abort the lifecycle when a create hook exits non-zero (run/teardown never abort) | true | Project |
hooks.repoScriptsEnabled | Run repo-committed hooks from .plexus/hooks.json instead of app-managed ones | true | Project |
Performance
| Key | What it does | Default | Scope |
|---|---|---|---|
session.maxWarm | Cap on warm (live) sessions before the least-recently-used idle one is evicted; 0 = unlimited | 8 | Project |
reviewCycle.maxRounds | Maximum review → fix rounds before a cycle stops on its own | 10 | Project |
Privacy
Plexus sends anonymous usage analytics — coarse operating system, app version, and a daily-rotating salted hash of your install so we can count daily active users without ever linking you across days. It never includes your code, file paths, prompts, or repository names, it's stored in the EU, and it's on by default. Turn it off any time with analytics.enabled. Full detail is in our Privacy Policy.
| Key | What it does | Default | Scope |
|---|---|---|---|
analytics.enabled | Send anonymous usage analytics (coarse OS + app version + a daily-rotating install hash; never your code, paths, or repo names) | true | Global |
Keybindings
All keybinding.* settings are global-only strings. Mod matches Cmd on macOS and Ctrl on Windows/Linux. Rebind, reset, or unbind each in the Keybindings category — see Keyboard shortcuts for the full set and their defaults.