Settings categories and access
Open Settings with Command–comma, the window gear, app menu or command palette. These routes share one editor. Search category names and keywords across the Settings window; Profiles, Loadouts and Security also have direct configuration entry points.
Use the controls and source-defaults appendix for exact static labels. Defaults there are initializers, not your current values. Controls can be conditional, and a field placeholder is not a default or validation guarantee.
Example: reduce noise without hiding urgent work
This is a Settings procedure, not a configuration-file snippet. It changes local notification policy without starting an agent.
- Open Settings → Notifications.
- Set Completed runs to Silent.
- Set Approvals to Critical.
- Check Show macOS banners, Play notification sounds and the app's macOS notification permission.
Expected result: completed-run items remain in the feed without interrupting you. Approval items can produce an ordinary authorized banner with sound. “Critical” is Commandem's delivery level, not Apple's Critical Alerts entitlement. Compare the notification controls; if delivery is missing, follow notification troubleshooting.
| Delivery level | In-app feed | OS interruption |
|---|---|---|
| Critical | Included when the feed is enabled. | Banner and sound, subject to master toggles and OS permission. |
| Alert | Included when the feed is enabled. | Banner, no sound. |
| Silent | Included when the feed is enabled. | None. |
| Off | Excluded. | None. |
Inspect CLI preferences and role bindings
Replace PROJECT with a registered project. These read-only commands inspect CLI configuration and resolved role bindings, not every macOS Settings control. Review local account labels before sharing their output.
commandem prefs default_mode
commandem prefs max_fanout
commandem roles PROJECT --jsonExpected result: the stored CLI default mode, or an explicit “not set” message, then resolved role bindings and their sources. max_fanout accepts 1–16 and has a source default of 6. COMMANDEM_MAX_FANOUT can override the effective fanout; the stored preference query does not resolve that environment override. See prefs and Loadout scope before changing either.
Profiles
Access: Settings → Profiles.
Provider configuration, named accounts, model/effort defaults, display identity, automatic continuation and exhaustion rules.
Scope and boundary: A display name is cosmetic, not a new model persona. Auto-continuation can spend quota; verify selected accounts and explicit fallback. If the control is unavailable, inspect the relevant provider/dependency instead of assuming the operation succeeded.
Agents center
Access: Settings → Profiles → Manage Profiles → Agents. Select a registered project in Defaults to list its .claude/agents definitions.
New persona requires a name and description. The editor exposes instructions, model and tools; an existing name stays fixed, and deleting a file requires confirmation. These project instruction files are separate from Loadout routing and security persona policy. Authoring a file does not launch an agent.
The list also includes VS Code definitions from .github/agents/*.agent.md, labeled VS Code, read-only. Definitions in .claude/agents/*.md are editable here; a same-name editable definition takes listing precedence. To adapt a read-only definition, choose Make editable copy, review the name, description and instructions, then explicitly create the new .claude file. The original remains unchanged. VS Code model and tools overrides are left blank because their names are not the editable file’s vocabulary; review compatible overrides rather than assuming they transferred. Making a copy does not launch an agent or change the Guardrail profile. Use the Agents CLI reference to inspect definition provenance.
Source note: listing/read boundaries additionally reviewed at CLI 61d89aeb; editable-copy behavior at desktop 83579f9a. The previous handbook baseline was 11249a60; the current source review is shown above. This section does not certify an installed build or whole-handbook currency.
Starter personas: when no editable personas are present, choose a work type to preview the starter set. Add creates project files only after that choice; Skip leaves them unchanged. Existing names, including read-only definitions, are kept. An editable persona also offers Duplicate. A failed instructions read disables Save until Retry succeeds, preserving the original body.
Loadouts
Access: Settings → Loadouts.
Reusable per-role routing, behavior, tool and account references. Loadouts can reference projects and workspace/environment choices without copying credentials.
Scope and boundary: A saved configuration is not an authenticated account. A role binding should not silently replace an unknown profile. If the control is unavailable, inspect the relevant provider/dependency instead of assuming the operation succeeded.
Security
Access: Settings → Security.
Tool approval boundaries, the Guardrail profile, local policy, standing directives, protected capabilities and permitted elevated behavior.
Scope and boundary: A hard-floor override requires its own gate. CapBroker has named limits; a passphrase alone is not protection against hostile same-user processes. If the control is unavailable, inspect the relevant provider/dependency instead of assuming the operation succeeded.
Chat defaults
Access: Settings → Chat defaults.
Behavior when sending/relaunching, suggestions, smart replies, model reminders, active-turn handling and unattended detach defaults.
Scope and boundary: Auto-resend and retry can invoke real agents. Persisted preferences can override the source initializer; inspect scope before resending sensitive material. If the control is unavailable, inspect the relevant provider/dependency instead of assuming the operation succeeded.
Audio
Access: Settings → Audio.
Microphone input, local dictation preferences, voice-command confirmation, speech playback voice/rate/volume and auto-read.
Scope and boundary: Hardware and OS permissions are separate. Speech engine support varies; preview/confirmation is not arbitrary voice-command authority. If the control is unavailable, inspect the relevant provider/dependency instead of assuming the operation succeeded.
Notifications
Access: Settings → Notifications.
Per-type delivery and priority, quiet behavior and notification appearance. Ordinary feed notifications retain their read/dismiss state. Board messages remain non-notifying Board/Activity audit records, with separate unread/read and history semantics.
Scope and boundary: OS permissions can block banners or sound. Clear/read does not delete history or eliminate an unresolved project condition. If the control is unavailable, inspect the relevant provider/dependency instead of assuming the operation succeeded.
Appearance
Access: Settings → Appearance.
Theme, accent, status colors, density, sender/timestamps, thinking labels, tool folding, fonts, bubbles, backgrounds and rendering preferences.
Scope and boundary: These are local presentation choices. A collapsed or abbreviated thinking display is not a full model reasoning transcript. If the control is unavailable, inspect the relevant provider/dependency instead of assuming the operation succeeded.
Conversation styles and scrolling
Under Appearance → Conversation appearance, apply Bubbles for the standard blue treatment, VS Code for flat, left-aligned monospaced text, or Compact for 90% text and the Fast animation setting. Each preset applies once; changing a bundled setting afterward shows Custom. Theme, background, provider, model, account and automatic scrolling are separate choices.
Auto-scroll offers Always, Only when at bottom (the default), and Never. Opening a conversation and explicit navigation are separate from following incoming content. Use Latest to catch up manually in every mode. A local send can jump to the bottom except in Never; opening a conversation remains explicit navigation. Expand Show full thinking to read the whole stored status update; the collapsed preview is abbreviated, and neither view certifies a complete private reasoning transcript. Changing appearance does not restart the conversation.
Layout
Access: Settings → Layout.
Sidebar grouping/sort/visibility, tab groups and icons, splits, second-pane behavior, file-link target, hidden/ignored files and infrastructure visibility.
Scope and boundary: Layout hiding is not deletion. File handlers are installed separately; showing ignored files can expose sensitive local configuration. If the control is unavailable, inspect the relevant provider/dependency instead of assuming the operation succeeded.
Projects
Access: Settings → Projects.
How projects are listed and opened, default interaction behavior and project-oriented preferences. Inspect selected project scope before changing configuration.
Scope and boundary: Project defaults and global settings are different. Registry entries refer to local directories; a project listing is not proof its source exists. If the control is unavailable, inspect the relevant provider/dependency instead of assuming the operation succeeded.
Mobile
Access: Settings → Mobile.
Pairing and trusted-device configuration for the supported companion path.
Scope and boundary: Device pairing and OS/network behavior need separate physical-device acceptance. Do not imply public anonymous access or broad platform certification. If the control is unavailable, inspect the relevant provider/dependency instead of assuming the operation succeeded.
Input
Access: Settings → Input (formerly Keyboard).
Configurable keyboard bindings and their current overrides. See the shortcut reference for source defaults. Mouse gestures are live desktop controls in the Mouse gestures section below. The separate Gesture binding files tools inspect, import, export and edit metadata; those imported/exported files do not activate capture or actions. Loading for editing can create private storage or archive an invalid owned file; inspection and import preserve the selected source. Preserve pending edits and inspect recovery notices before replacing a document.
Scope and boundary: Defaults apply only where the action is handled; focus, local overrides and OS shortcuts can change the effective behavior. If the control is unavailable, inspect the relevant provider/dependency instead of assuming the operation succeeded.
Mouse gestures
Access: Settings → Input → Mouse gestures. Enable mouse gestures, then start a right-button drag on the visible gesture strip at the bottom of a project pane, draw, and release.
The live preview names the current action and originating pane before release. Defaults are ← / → for previous / next tab, ↑ / ↓ for previous / next project, ↓→ for Close tab, and ↑← for Undo close tab. Tab navigation wraps; project navigation follows visible sidebar order without wrapping. A right-pane project gesture changes that pinned pane.
Gestures start off. Enable or disable all gestures or the selected action. Select an action, enter 1–4 directions using L, R, U and D, then choose Apply. Consecutive repeats and duplicate strokes are refused; Swap explicitly exchanges conflicting actions’ strokes. Reset default strokes restores the six defaults. The practice area records a stroke without running an action or changing a binding; review it and use Apply to activate it.
Cancellation: Escape cancels the held sequence. An unmatched, disabled, unavailable or overlong stroke performs nothing and opens no menu. An ordinary undrawn right-click retains native handling. Context changes, Settings changes, deactivation and a 10-second timeout cancel capture. Editors, links, transcript controls and splitters retain their mouse ownership; they are not capture surfaces.
Close and undo: The original chat can be reordered and, when siblings remain, closed like any other chat. Closing a busy chat when siblings remain asks before stopping its turn; save or revert dirty files and resolve conflicting composer drafts before closing those tabs. Only the sole remaining tab uses Last chat tab fallback, preserving that tab and any conversation. Undo restores the same tab identity, moved namespace or file descriptor, and its retained draft/preferences. It is also available from the menu and Command+Shift+T in the focused chat pane. History is memory-only: 10 closures per pane, 32 across the app, for 30 minutes; restart clears it. An expired, occupied or changed namespace cannot be replaced by a fresh chat.
Scope and boundary: These six actions are local navigation and tab lifecycle only; no prompt is sent or tool approved. Imported binding files remain inspection-only. Physical gesture calibration, trackpad swipes, extra buttons and mobile gestures require separate acceptance. An older installed build may still have only the file tools.
System
Access: Settings → System.
Launch/quit behavior, raw settings access, integrations, recipe registry configuration, dependencies and backup/export tools.
Scope and boundary: Workspace exports exclude chat archives; full backups may contain sensitive state. Review contents and permissions before sharing or importing. If the control is unavailable, inspect the relevant provider/dependency instead of assuming the operation succeeded.
Persistence and precedence
Global app preferences, project overrides, named provider accounts, Loadout role bindings and per-pane selections are different scopes. A stored value can override a source initializer. Changing presentation does not change provider credentials, and changing a mode does not grant execution authority.
For account selection follow the account workflow. For notification mismatch, file-handler failures or missing resources follow Troubleshooting. Review Privacy before exporting state.
Current source boundaries
These are source-level boundaries reviewed against 8f06da03. They do not replace the dated source captions or screenshots elsewhere in this handbook, or certify installed-app, physical-input, device, provider or OS-permission behavior.
Explicit local model refresh
Local Profiles includes Refresh models as a separate action from saving the server configuration. The control is disabled while automatic discovery or its own refresh is busy. A saved server or a completed UI action alone is not proof that a model is installed, an account is authenticated or the provider is ready.
Non-default Local model rows show available capability evidence, size information and estimate advisories. Try… opens a prompt; Send invokes that model. Grade runs the deterministic battery, caches its reported tier and refreshes the catalog. Both use the configured server, which may be remote or metered; a Local badge does not certify locality, price or production tool safety. Chat with it selects the Local agent and model for the current global or project scope, then closes Settings. Open Chat to send a turn.
Agent Builder: with a project selected, the Agents center offers Agent Builder… alongside Starter personas…. The sheet supports definition authoring from a template or a Managed Agents import. Review the definition before explicitly creating or importing project files. Opening the builder or authoring a definition does not launch an agent, deploy a hosted agent or grant execution authority.
Activity, notification policy and directive reminders
Board messages remain Board/Activity audit records and do not produce human notifications or OS banners. The source defaults for killed-run and system notifications are off; saved user policy can differ. A directive-sync reminder uses its own 600-second polling interval and is skipped when the directive_sync preference is off. Its count is not a complete content-change detector.
Sync now is an explicit fleet-wide brief --apply action, separate from reading the reminder. The count may clear optimistically while the actual result is reported; clearing it is not proof that every project was successfully updated. OS notification permission remains a separate requirement.
Due agent reminders and roadmap/GitHub sync conflicts have separate Reminders and Sync conflicts notification types. Both source-default to Alert; saved policy and macOS permissions still control delivery. A reminder offers Open project and Dismiss. Its Dismiss action disables the reminder, rather than merely clearing unread state. The row is removed optimistically, so inspect any reported failure; disappearance alone does not confirm cancellation.
A single-project sync conflict offers Open roadmap; a fleet-wide conflict offers List conflicts, which runs the conflict listing. Opening or listing a conflict does not resolve its fields or choose which side wins. Clear All remains a separate unread-state action.
Pairing countdown and refresh limits
The pairing countdown uses the response's TTL, with 300 seconds as the fallback. While the pairing view remains active, automatic rearming is bounded to six refreshes; Generate new code remains an explicit control. A countdown or paired label is not fresh physical-device, revocation or network acceptance.
Input feedback and existing declarations
Enabled mouse gestures can start with the middle button in project panes or the sidebar as well as through the existing right-button bottom strip. A plain middle click does not by itself execute a gesture. Practice hints show the current keyboard binding and follow feedback sizing, even when unsolicited live feedback is hidden. Existing cancellation and exact-match rules still apply; this is not a global mouse remapper.
The Audio source declaration retains its pending, last-loaded and read-only distinctions: a saved voice is not known unavailable until checked, and pending refresh does not start another lookup. The existing Roles, toolbar, archive-reader and Cursor-preview declarations keep their original scope and runtime limits. Test seams, generated design tokens and diagnostic traces do not add user-facing capabilities or certify those controls.