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 — Start new sessions automatically, Let the agent work without asking permission — are decided before the session exists, so they always resolve from the project layer, never the session itself.

The Settings UI

Open global Settings to edit defaults that apply everywhere. Rows are grouped into five pages — General, Agent, Git & PRs, Worktrees & Hooks, and Advanced — plus dedicated pages for Appearance, Git providers, Keybindings, and About, so you can find a setting without scrolling a flat list. Connecting GitHub or Bitbucket lives under Git providers — see Connections.

Within a page, related rows sit under a labelled section — Pull requests, Code review, Fetching and remotes and so on — each with a one-line description of what the group covers. The reference below mirrors those sections exactly.

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

Every scope has its own Settings… entry: a project's is in the ⋯ menu on its sidebar row, and a workspace's is in the workspace menu in the app bar — or, if you set Workspace navigation to All workspaces in the sidebar, in the ⋯ menu on the workspace's own row. At these scopes each section carries its own Override parent settings switch, next to its heading:

• Off — every row in that section 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 — that section's rows become editable; anything you change is an override applied to this scope and everything inside it.

Sections are independent: turning on Copied files for a project leaves Session folders and Lifecycle hooks inheriting. Turning a switch back off unsets every override in that section at this layer, and leaves the rest of the page alone.

A page that only has a handful of settings at this scope — General and Advanced, where most rows are global-only — keeps a single Override parent settings toggle for the whole page instead. A section disappears entirely when none of its settings can be set at that layer.

The lifecycle-hooks editor at the bottom of Worktrees & Hooks is not governed by the Lifecycle hooks switch — it has its own per-layer inheritance, described in Hooks.

Some settings are global-only — the terminal shell, the agent path, diagnostics, Gravatar avatars, the editor's save mode, and all keybindings — and don't appear on workspace or project pages, because they describe the machine, not a scope. Everything on Appearance goes further: those are per-machine preferences that appear on no workspace or project page at all.

Appearance

Settings → Appearance holds three choices about how Plexus looks and how the sidebar is shaped. Each is a pair of cards with a small diagram of the layout it produces.

Theme

Dark, Light, or Match system, which is what a new install uses and which follows your operating system's light/dark setting as it changes during the day. The choice applies app-wide, including the Explorer editor and the terminal. The theme button in the app bar is a shortcut that swings between light and dark; this page is where you get back to following the system.

Density

How much a session row says — a layout mode, not a spacing slider.

Normal (the default) gives each session two lines: its name, then the branch it is on and what the agent is doing in words — Working, Needs you, Idle, or Delegating when the agent isn't mid-turn but background subagents are still running. A single icon beside the branch name carries both facts about that branch: its shape marks a branch Plexus did not create, so you can see which sessions Rebase or Squash would be rewriting shared history on, and its colour is the pull-request status — click it to open the pull request.

Compact is one line per session: the name, the coloured activity dot and the pull-request icon. It fits roughly twice as many sessions on screen, which is the point when five to ten are live at once.

You can also switch between them from the app bar, next to the Settings button.

Workspace navigation

Switcher in the header (the default) keeps one workspace active at a time, chosen from the switcher in the app bar. The sidebar is then two levels — projects over sessions — so a project is the first thing you see and a session is one step in. The switcher's menu lists every workspace with its session count and how many are waiting on you.

All workspaces in the sidebar restores the three-level tree: every workspace as a collapsible section, with its projects and their sessions nested inside.

Settings reference

Where you set it is the narrowest layer a setting can change at: Global only means it's a per-machine choice; Global → Project means you set a default globally and can override it per workspace or project (sessions inherit from their project); Per session means it can be tuned for each individual session.

General

Notifications

How Plexus gets your attention when a session needs you.

Custom sound. By default the chime is synthesized in-app, but you can replace it with your own audio file under global Settings → General → Custom sound (.wav, .mp3, .ogg, .flac, .m4a, and more, up to 5 MB), directly beneath the Notification sound toggle. 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 Notification sound toggle still decides whether any sound plays.

Sessions and files

What Plexus does with a session's folder, and with your edits.

Agent

Permissions and startup

How freely the agent runs, and whether sessions start themselves.

Model and reasoning

Which model your sessions use, and how hard it thinks.

Input and controls

The compose box and buttons you see while a session runs.

Session summary

The sidebar recap that refreshes when the agent stops.

This isn't the only place AI session summary can be switched on. Every session has a Summary button whether or not the setting is on, and opening that panel while it's off explains what a summary is and what it costs, with Turn on for <project> and Turn on everywhere — the same setting, written at the project or the global layer, followed by a first summary straight away. See Session summary. Switching it back off is done here.

Git & PRs

Pull requests

How Plexus drafts, tracks, and cleans up after a pull request.

Code review

How the agent reviews your changes, and how the review-and-fix cycle behaves.

Commit messages

How the agent writes a message from your staged changes.

Fetching and remotes

What Plexus downloads from your remotes, and how often.

The Default Pull action is also settable from the Pull button's own menu — its Default action picker saves the choice for that project. That same menu carries Fetch automatically, which turns automatic fetching on or off for that one project. Automatic fetching talks only to the git remotes you configured, using the credentials git already has; see Automatic fetching and the Privacy Policy. Suggest a rebase when the base branch moves ahead rides on those same fetches instead of making its own, so with automatic fetching off its count only changes when you fetch by hand. Fetch the base branch before rebasing or merging is the one that does make its own request — turn it off for a project on a metered connection, an offline machine, or a remote that wants to prompt you for credentials. Turning it off never blocks the operation, and neither does a failure: with the setting on, a download that doesn't succeed still lets the rebase or merge run against the last version Plexus fetched, with a warning that the base may be out of date. Show commit author avatars from 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.

Connection checks

How Plexus notices that a provider has narrowed what it granted.

Check that provider connections still work is what catches a permission that was withdrawn on the provider's side — the kind of change that otherwise stays invisible until a repository search or a pull request fails. It talks only to GitHub or Bitbucket, from your machine, with the token already stored there. Raise How often to check provider connections (hours) on a metered connection or an account close to its provider's rate limits.

Worktrees & Hooks

Session folders

Where each session gets its own copy of your project.

Copied files

Untracked files like .env that a new session needs.

Dev server ports

A unique block of localhost ports per session, so two dev servers never collide.

Lifecycle hooks

Scripts that run as a session is created, started, or removed.

The hooks editor itself sits at the bottom of this section. It keeps its own per-layer inheritance, so the section's Override parent settings switch does not govern it — see Hooks.

Advanced

This page isn't split into sections — most of its rows are per-machine escape hatches you'll rarely touch.

Turning Diagnostic logging on reveals a Reveal log button that opens the folder containing plexus-diag.log.

Beside it — and available whether or not the toggle is on — is Copy session diagnostics. Plexus always keeps the last few hundred lines of session start/stop activity in memory: which stage each start reached, how long each one took, and where it stopped. The button copies them to your clipboard so you can paste them into a bug report. This is the quickest thing to send if a session won't start, and it works even if you only think to look after it happened.

That trail is kept in memory only. Save diagnostics when a session gets stuck is what also writes it to plexus-diag.log when a start or resume times out or is cancelled, so it survives quitting Plexus. It's off by default because it puts repository paths, branch names and worktree folders on your disk; turn it on if you're chasing a session that only wedges occasionally. Diagnostic logging already covers this, so you don't need both.

The log file doesn't grow forever: every time Plexus starts it drops lines older than Delete diagnostic logs after (days), which is 7 by default. Set it to 0 to keep everything — useful when you're capturing a problem that takes weeks to reappear. The change takes effect at the next launch. If you pinned the log somewhere yourself with the PLEXUS_DIAG environment variable, Plexus leaves that file alone.

Keybindings

Every keyboard shortcut is a global-only setting. Mod matches Cmd on macOS and Ctrl on Windows/Linux. Rebind, reset, or unbind each one in the Keybindings panel — see Keyboard shortcuts for the full set and their defaults.