Settings

This page lists every Plexus setting with its default and explains how settings cascade from global to workspace, project and session. 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.

There is one thing above all four, and it is not a layer you can write to: a value your organization enforces. Precedence, from the value that wins down to the one that applies when nothing else does, is:

Enforced by your organization  →  Session  →  Project  →  Workspace  →  Global  →  built-in default

An enforced value wins over a session's, a project's, a workspace's and your global one alike, and its row is read-only wherever it appears; your own value is kept underneath and returns when the organization stops managing it. A value an organization merely recommends is written into your global layer once, exactly as if you had set it there, and behaves as a global value from then on. See Managed settings.

Those four layers are about which scope a value applies to. Which machines it applies to is a separate question, and the answer is "only this one" until you turn on cross-device sync — after which your global, workspace and project values follow you, and your session-level ones still don't.

The Settings UI

Open Settings from the gear in the app bar. The sidebar lists nine pages, General, Appearance, Agent, Git, Integrations, Worktrees & hooks, Shortcuts, Prompts and About, and at its foot, under your name and plan (or Sign in), the account group: My account, Sync and Organizations.

Each page is a short list. A setting's name is on the left and its current value on the right, and related rows sit under a small heading such as Pull requests, Code review or Fetching and remotes; the reference below mirrors those headings. A value set at the level you're looking at is shown in full colour, and one that comes from further up is shown muted.

Select a row and a side panel opens on the right with:

• one sentence on what the setting does;
• the choices, the switch or the field, which take effect as you change them;
• Where this comes from: the default, a value inherited from a workspace or from global, a value set here, or a value your organization manages, with the button that takes you back to the value above (see Overriding at a workspace or project); at global, a value you've changed has Reset to default;
• More detail, the full explanation, when there is more to say than the one sentence.

Switches can be flipped straight from the list without opening the side panel. On a narrow window the side panel slides over the list instead of sitting beside it.

A row your organization manages is marked too. An enforced row shows a lock in place of its arrow, and its side panel says Set by Acme. Ask an admin to change it. A recommended value looks like any other value; its side panel says it came from your organization's recommendation. See Managed settings.

Some pages hold more than settings, and their rows open the same side panel:

• Git starts with Providers: one row each for GitHub and Bitbucket, where you connect, reconnect or disconnect. See Connections.
• Integrations holds no settings at all, only your connections to services that are not git hosts: under Plnnrly, one row per Plnnrly organization you connected and an Add Plnnrly organization row. See Integrations.
• Shortcuts has one row per keyboard shortcut. See Keyboard shortcuts.
• Prompts has one row per saved prompt template.
• About has the version and Check for updates, What's new, the connected accounts and the open-source notices.

My account is not a settings page at all. It holds no settings, only your sign-in, your own plan and your signed-in devices, which is why it never appears on a workspace or project. Your organizations are not on it either; they have their own Organizations page, right below it. See Your Plexus account.

Organizations holds no settings of its own either. It is everything about an organization, one organization at a time: pick one from the organization picker at the top, and the rows below are about that one: Name, Plan, seats and people, Shared workspaces, Managed settings and Published prompts, each of which opens in the side panel. That covers its people and plan, the workspaces it shares, the settings it manages on this machine and the prompts it publishes. The page appears whether or not you are in an organization: signed out it offers to sign you in, and with no organization it offers to create the first.

Sync is where the settings on every other page can be made to follow you to your other machines. See Cross-device sync. Nothing on this page leaves your computer until you turn sync on there and approve a list of exactly what would go.

A setting whose value is one of a list shows its choices in the side panel; pick one and it's saved.

Overriding at a workspace or project

Every workspace and project 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. The Settings button at the right end of a project's or a workspace's tab strip opens the same screen, on its Toolchain page.

Opened that way, Settings shows Applies to at the top: Everywhere, the workspace, and (from a project) the project. Pick the level you want to change. The sidebar then shows only the pages that have something to set at that level: General, Agent, Git, Worktrees & hooks, Toolchain and Prompts. Everywhere is your global settings; the same choice takes you back to the workspace or project.

At a workspace or project, every setting overrides on its own:

• A row shows the value it inherits, and the side panel says where it comes from. A new workspace or project changes nothing until you change a row.
• Change a value and it is overridden at this level, for this scope and everything inside it. Every other row keeps inheriting.
• To undo an override, open the row and press Use workspace value (on a project) or Use global value (on a workspace); the button shows the value you'd get back. When no layer above sets one, it reads Use built-in default.

A row your organization enforces stays locked at every level, with Set by Acme. Ask an admin to change it. in its side panel. An enforced value is not one of the layers, so there is nothing to override; a value you set before it was enforced is kept underneath and returns when the organization stops managing the setting.

The lifecycle-hooks editor on Worktrees & hooks, the Create, Run and Teardown rows, keeps 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, the two sync switches, and all shortcuts) 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.

One page runs the other way. Toolchain exists only on a workspace's or a project's settings and never on the global screen: it holds no settings rows at all, but the catalogue of tools attached to that scope, a Share with projects switch on each of a workspace's tools, and a project's Inherit the workspace's tools switch. Nothing on it is an override, because a project adds to what it inherits rather than replacing it, and none of it travels with sync. See Toolchain.

Appearance

Settings → Appearance holds three choices about how Plexus looks and how the sidebar is shaped: Theme, Density and Workspace navigation. Select one and its side panel shows the choices as cards, each 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 work is 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 in the Custom sound row on global Settings → General (.wav, .mp3, .ogg, .flac, .m4a, and more, up to 5 MB), directly beneath the Notification sound row. 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.

Terminal

The shell Plexus opens for the built-in terminal and for installers.

Performance

How many sessions stay loaded and ready to switch back to.

Claude CLI

Where to find the claude program on this computer.

Diagnostics

Troubleshooting logs to send us when something goes wrong.

Select the Diagnostic logging row and its side panel has a Reveal log button, shown while the setting is on, that opens the folder containing plexus-diag.log.

Beside it — and available whether or not the setting 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.

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

Providers

The GitHub and Bitbucket connections Plexus uses for pull requests, issues and fetching.

There is one row for GitHub and one for Bitbucket, each showing whether it's connected. Select one to Connect, Reconnect or Disconnect it in the side panel. These are global only: a connection belongs to this machine, not to a workspace or project. See Connections.

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.

Stacks

How Plexus keeps a stack of sessions in sync, how it shows a stack on GitHub, and how it merges one. Syncing, GitHub stacks and merging need a plan; without one these settings are kept but have nothing to drive.

When a sync conflicts replaces the two conflict settings earlier versions had — one for restacking and one for landing — and updating keeps the stricter of what you had chosen: if either was set to stop, it is Stop; a landing setting you had set to ask first stays Ask me first; otherwise it is the new default, Hand it to the session's agent.

Push after syncing, Create stacks on GitHub and List the stack in pull request descriptions are the three that change something other people can see on your provider, so each is a switch of its own. An automatic sync never rewrites a branch you checked out from an existing branch rather than one Plexus created — only Sync now does — and none of these settings talks to anything but your own git provider, from your machine.

Integrations

Plnnrly

The Plnnrly organizations Plexus is connected to, for the Plnnrly tabs.

There is one row per organization, reading who is signed in — Alex Smith, or Signed in — and a last row, Add Plnnrly organization, which asks for the Organization address and then lets you Sign in with Plnnrly, the only way to connect. An organization whose Plnnrly does not offer sign-in for apps yet says so, with Check again. Select an organization's row to Reconnect or Disconnect it in the side panel. There are no setting keys here, and the page is global only: a connection belongs to this machine, not to a workspace or project, and it does not travel with sync. See Plnnrly.

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, as one row each for Create, Run and Teardown; select one to edit that event's scripts in the side panel. It keeps its own per-layer inheritance, separate from the rows above. See Hooks.

Shortcuts

Every keyboard shortcut is a global-only setting. Mod matches Cmd on macOS and Ctrl on Windows/Linux. The page has one row per action with its current combo; select one to record a new combo, reset it or unbind it in the side panel. See Keyboard shortcuts for the full set and their defaults.

Prompts

Your saved prompt templates live on this page, one row each, above the one setting that decides what the list contains. Select a template to read it or edit it in the side panel. At a workspace or project, the page shows only that setting.

From a repository

Sync

Whether the settings on every other page follow you to your other machines. The page is only usable while you are signed in to a Plexus account whose plan includes sync; without one it shows what the feature does and how to get it.

Cross-device

Both are per machine and never travel: a synced off-switch would turn sync off on every computer you own the moment you turned it off on one. The rest of the page — the preview of what this machine sends, per-project exclusions, the version history, Sync now, and Stop syncing and forget what we hold — is described in Cross-device sync.

Organizations

No settings of its own. The page is global-only and appears on no workspace or project page, because there is nothing here to override. It needs a Plexus account — signed out, it offers to sign you in; signed in with no organization, it offers to create the first.

Across the top is an organization picker listing every organization you belong to, with New organization in it. Everything below is about the organization you picked, as five rows that each open in the side panel: Name (its name, slug, your role and how many people are in it, with Rename and Delete), then the four below. Switching organizations switches all of them, and nothing about an organization is read until it is the one on screen.

Plan, seats and people

The organization's plan and seat count, Buy seats / Update seats / Manage billing for whoever holds the billing permission, Invite someone, and the list of members and pending invitations with Give a seat / Take back seat and Remove. This is where an organization's whole billing side lives in the app — your own plan stays on My account. See Plans, seats and billing.

Shared workspaces

The organization-workspaces surface for this organization: what it shares with you, Join / Ask to join on the ones you are not in, and Manage for the administrator half.

Managed settings

The settings this organization manages on this machine: each setting it recommends, enforces or is evaluating, when the list was last checked, Refresh, and Manage for the administrator half — publishing, changing a level, enforcing, withdrawing, and the dry-run counts. The values themselves are not edited here: an enforced one shows up locked on its own settings page, and a recommended one shows up there as an ordinary value whose side panel says where it came from.

Published prompts

The prompt templates this organization publishes to this machine: each template with its revision number, when the list was last checked, Refresh, and Manage for the administrator half — proposing, publishing a draft, rolling back, discarding a draft, deleting, and reading a template's revisions. The templates themselves are run from the same pickers as your own, badged Org · Acme; they are not edited here or on the Prompts page, because they are the organization's.

The last three each need the organization's plan to include that feature and you to hold a seat on it. When it does not, that row's side panel shows what the feature is and how to get it — for this organization only; the other rows, and your other organizations, are unaffected.