Fermata settings, pane by pane

Settings opens with ⌘, and is organized as panes down the left, in this order: General, Sessions, Loop, Project, Streams, Notifications, Mobile, MCP, Storage, Edge, and Pro & Dev. Two of them appear only when they apply: Streams needs Edge plus its Loop intake switch, and Mobile needs Pro. Edge is listed on every channel, because it is the only place to turn Edge on. Almost everything here is a default for new work. Changing a default never reaches back into a session or a piece that is already running. Two panes are worth knowing about before the rest. Sessions and Loop hold separate defaults for the two kinds of work, so a change in one does not affect the other. Project overrides either of them for a single project. Where defaults live explains which one wins.

General

Grouped into Getting Started, Interface, Power, Updates & Privacy, and Integrations.

Setting	What it does
Replay Welcome Tour	Replays the welcome card and the short tour of Home, Canvas, Loop, and the inspector.
Show in menu bar	Puts awake, Loop, and attention status in the menu bar.
Auto-scroll console to latest	Follows new log entries as they arrive.
Wrap long console lines	Shows full entries on multiple lines instead of truncating them.
Show newest activity first	Puts the most recent events at the top of the activity feed.
Terminal font size	Point size for the embedded terminal text only.
Text Size	Scales text across the app. Icons and the embedded terminal keep their own size.
Show a scroll bar on boards that scroll sideways	Under Scroll Bar. A draggable bar with paging arrows in the margin below the board. Trackpad and mouse scrolling work either way.
Prevent the Mac from sleeping	Under Keep Mac Awake. Holds the system awake so agents keep running. Off by default. Turning it on reveals While Agents Run and While App Is Open. Worth setting before you leave a hands-off run going.
Keep the display awake too	Also prevents the screen from sleeping. Uses more power.
Automatically check for updates	Periodic update checks, plus a Check for Updates Now button.
Send anonymous usage data	Anonymous counts of which features are used. On by default.
Send crash & freeze reports	Stack traces when Fermata crashes or freezes, so bugs can be fixed. On by default.
External Editor	Which editor a session’s Open in button launches: “None”, “VS Code”, “Cursor”, “Windsurf”, “Xcode”, “Zed”, or “Custom” with your own CLI command and app path. The pane shows whether the one you picked is installed.
Claude Config Directory	Points every session at a different Claude configuration folder, and decides which `settings.json` the model picker mirrors and which account Home’s usage tiles probe. The helper text reads “Overrides CLAUDE_CONFIG_DIR for every session. Leave it empty to use the CLAUDE_CONFIG_DIR Fermata was launched with, or ~/.claude when there is none.”

The two privacy rows are the same two choices the first-run notice offers, worded identically. See Privacy and data for what each one sends.

Sessions

Defaults for standalone sessions, the ones you start on the Canvas. Grouped into Model, Defaults, Worktrees, and Experimental.

Setting	What it does
Default Model	The model new sessions start on. Changeable per session when you spawn it.
”Model Provider”	Shows the provider detected from your environment, with a Force Anthropic API option for anything but the direct API, and a Re-read button when a gateway is detected. See Models and providers.
Default Permissions	The permission profile new sessions get. Applies to sessions you start yourself, not to pieces. See Where defaults live.
Open Sessions In	”New Window” or “Main Window”. Main Window shows the session inline in the center, keeping the sidebar and inspector.
Use worktrees by default	Under Git Worktrees, subtitled “Each new session gets its own worktree and git branch. Pieces always do.” It governs sessions only. Off by default, so sessions run in your checkout unless you turn this on. A piece always runs in its own worktree, whatever this toggle says.
Worktree Conventions	”Applies to new sessions. Worktree location and base branch also apply to new pieces; pieces take their branch pattern from the Loop tab. Existing sessions keep the values they were spawned with.” Branch pattern applies to sessions only and takes `{session}` (required), `{piece}` (the piece a session was started from, empty otherwise), and `{date}`; the default is `fermata/{session}`. Worktree location and Base branch apply to new sessions and pieces alike. Leave Base branch empty to auto-detect each project’s default branch. Per-project overrides live in the Project tab, under Branch Behavior.
Enable experimental Agent Teams	Under Experimental: Agent Teams. Lets a session spawn in-process teammates that share its worktree. Applies to every new session, requires Claude Code 2.1.32+, and uses significantly more tokens per session.

Loop

Defaults for pieces: the model, how hands-off a run is, and how many agents may run at once. Grouped into Model, Execution, Autonomy, Interview, and Lifecycle.

Setting	What it does
Default Model	The model new pieces use. Each phase can override it.
Default Effort	Reasoning effort for new pieces. “Auto” uses the CLI default.
Git Worktrees	A fixed rule, not a toggle: “Pieces always run in their own worktree. All agents on a piece share its branch, and changes are committed per agent.” The run refuses to start without a worktree.
Worktree Conventions	Branch pattern for pieces. Takes `{piece}` and `{date}`. Applies to new pieces only. Per-project branch patterns apply to sessions, not pieces.
Limits	Parallel agents caps a single piece. Global cap is the ceiling across all of them, so the Loop cannot swamp your machine. See Limits.
Open a pull request when a hands-off run finishes	Under Pull Requests. Turn it off to finish the run locally, without a PR.
Piece Permissions	The permission profile new pieces get. Applies to the build agents and to the rework sessions you start from a review; the planning phases run without tool approvals either way. See Where defaults live.
Require Plan Approval	Parks the run at the plan gate. See Gates. The third park gate, strategy approval, has no default here; it is set per piece.
Require Review Before PR	Parks the run at review, before a pull request is opened. See Gates.
Run Code Review Before PR	A pass, not a stop. Runs the code review and attaches its findings as advisory context before opening the PR. Appears only with Edge and its Code review switch on.
Run Work Review After Agents	A pass, on by default: “After the agents finish, one fresh agent checks that the plan was followed and the work was done, and never edits anything.” See gates for what a failing verdict does.
Spec Interview Depth	How hard the interview pushes before it drafts: “Quick”, “Balanced”, or “Thorough”. The Project pane overrides it per project.
Automatically tear down the worktree when marked Done	Under Cleanup on Done. Skips the confirmation dialog and tears the worktree down. See what happens to the worktree.
Auto-Archive Done Pieces	Hides finished pieces from the Done column after 14, 30, or 90 days. “Off” by default. Archiving is reversible and deletes nothing: the spec, strategy, summary, and learnings all stay.

Piece Permissions is deliberately not the same control as the Sessions pane’s Default Permissions, and it starts on a looser setting. See how much happens without you for why.

Project

Per-project overrides. Every card inherits the global default until you switch the override on, and the card shows you what it is inheriting. The concurrency ceiling, your account, sync, and app-wide preferences stay global.

Setting	What it does
Default Model	One override governing both this project’s pieces and its sessions. A piece takes its model when it is created and then keeps it.
Default Permissions	The profile this project’s sessions run under, inheriting from the Sessions pane.
Piece Permissions	The profile this project’s pieces run under, inheriting from the Loop pane. Deliberately independent of the session override, so tightening one never moves the other.
Use Worktrees for Sessions	”Whether this project’s new sessions get their own worktree and branch. Pieces always run in a worktree.”
Default Effort	Reasoning effort for this project’s new pieces.
Spec Interview Depth	”Quick”, “Balanced”, or “Thorough”. See The interview and the spec.
Auto-Archive Done Pieces	”Off”, 14, 30, or 90 days, for this project.
Require Plan Approval, Require Review Before PR, Run Code Review Before PR, Run Work Review After Agents	The same two gates and two passes as the Loop pane, for this project only. Code review appears only with Edge on.
PR Conflict Resolution	How Fermata brings the base branch into a PR branch when resolving conflicts. “Merge” is the safe default: no force-push, stable PR commits. “Rebase” rewrites the branch and force-pushes.
Branch Behavior	Overrides the global worktree conventions for this project; leave a field empty to inherit the global default. Worktree location and Base branch apply to new sessions and pieces. Session branch pattern applies to sessions only, since pieces use the Loop tab’s pattern. Base branch is a menu, not a text field: “Auto-detect · main” style, naming the repo’s detected default first, then its other local branches, with a checkmark on the one in effect. A branch no longer in the repo still gets its own row, marked “missing” in red, instead of silently falling back.
Claude Config Directory	A Claude configuration folder for this project’s sessions only. The helper text reads “Overrides CLAUDE_CONFIG_DIR for this project’s sessions. Leave it empty to use the CLAUDE_CONFIG_DIR Fermata was launched with, or ~/.claude when there is none.”
Project Instructions	Standing context handed to every agent in this project. See Project instructions.

The Project tab's Branch Behavior card with the Base branch menu open, showing Auto-detect · main followed by the repo's other local branches — The Project tab's Branch Behavior card: the Base branch menu with Auto-detect and the repo's local branches

Streams

Appears only with Edge on and its Loop intake switch on.

Stream Sources are the accounts Fermata reads issues from; keys stay in your Keychain. The “Connect an account” row has Linear… and GitHub…; each connected account is a row naming the kind and the account (“Linear · Acme”) with a health line, and its menu has Check now and Disconnect account…. With a project picked in the scope switcher, the pane leads with that project’s Streams and splits the accounts into the ones this project reads and “Other accounts”. With “All projects” picked, it also carries Check for new issues every, the interval for Stream checks. See Connect Linear and GitHub and Add a stream.

The Streams pane in Settings with a Linear row and a GitHub row, each showing a health line, Check now and Remove, and the Connect Linear and Connect GitHub buttons below — Settings → Streams: the accounts Fermata reads issues from

Notifications

Setting	What it does
Required Input	Approvals and agent questions. The one to leave on.
Session Completed	Sessions that finish successfully.
Failures	Failed sessions, pull requests, and planning steps. Split out from completions deliberately, so muting the chatter never mutes the one thing that has to get through.
Piece phase changes	Subtitled “As a piece moves from one phase to the next”. Notifies as a piece moves between phases.
Play sound with notifications	Adds a sound to all of the above.

Mobile

Appears once the companion is available to your account.

Pairing for the phone companion: Generate Pairing QR Code, then scan it from the phone. Once paired, the pane shows the device name, live sync health, an “End-to-end encrypted” confirmation, and Unpair. See The phone companion.

MCP

The pane appears on every channel. The server is off until you turn on MCP server, and the rows that depend on it stay greyed out until then.

Setting	What it does
MCP server	”Let an outside Claude Code drive pieces locally”. Off by default.
Ask before runs and pull requests	”Approve each one in Fermata”: adds a confirmation card in front of every run and pull request a client asks for. Off by default.

The Preferred port field defaults to 8787: type a port and press Apply. Fermata tries that port first, then the next nine, then whatever the system offers; a port change takes effect at the next start or Retry, never underneath a call already in flight. Once the server is running, the pane shows the bound host and port, a health readout, and whether Claude Code currently has the server registered. The “Endpoint” card carries Register (or Unregister) and Regenerate Token. The “Connect a client” card switches between three methods, One-off, Shell alias, and Register, and its “Copy” row has Instructions and Inline Config. See connect a client.

Storage

Setting	What it does
Auto-Save	How often session state is written to disk: 15s, 30s, or 60s.
Keep full history for	Retention before old sessions compress to a summary: “1 day”, “7 days”, “14 days”, or “Forever”. Compression is permanent. Sessions stay visible either way; pin one from its context menu to keep its full history regardless of age.
Include subagent transcripts	Keeps subagent messages alongside the parent session. Costs disk, buys you the full picture later.

Edge

The channel switch, Enable Edge features, and a “Features” card with one switch per preview feature: Code review, Web diff viewer, Loop intake, and Cost ceiling. See Edge features.

Pro & Dev

“Current Tier” reads “Free” or “Pro”. Free is the whole desktop app, and nothing here is required for normal use. Pro is unlocked by an “Invite Code” during the phone companion’s beta. It turns on the companion and the sync it runs over, the spend insights cards on Analytics, and the cost ceiling behind Edge. See the phone companion. The Edge switch is not here. It has its own pane, described on Edge features.

Start here

The piece

How much happens without you

The Loop board

Streams and Tracks

Drive Fermata from Claude

Surfaces

Configuration

Mobile companion

Reference

Fermata settings, pane by pane

General

Sessions

Loop

Project

Streams

Notifications

Mobile

MCP

Storage

Edge

Pro & Dev