> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mains.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Settings

> Configure Mains's behavior and personalization

Access settings with **Cmd+S** or from the sidebar footer. Each section is also reachable directly at `/settings?section=<id>`.

| **Section**                           | **What it covers**                                            |
| ------------------------------------- | ------------------------------------------------------------- |
| **General**                           | Run detail, appearance, active agents, notifications, updates |
| **Git**                               | Worktrees, commit and PR generation instructions              |
| **Connections**                       | External services -- connect, sync, revoke                    |
| **Dashboard**                         | [Usage statistics](/stats) across workspaces and providers    |
| **Claude / Codex / Copilot / Cursor** | Per-provider agent configuration                              |

<Note>
  [Relay](/relay/overview) used to live in Settings. It's now a top-level route -- open **Relay** from the sidebar.
</Note>

## **General**

### Run

| **Setting**       | **Description**                                                    |
| ----------------- | ------------------------------------------------------------------ |
| **Run Detail**    | How much detail run output shows -- toggles tool calls and outputs |
| **Prevent Sleep** | Keep your Mac awake while a run is active                          |

### Appearance

| **Setting** | **Description**                                      |
| ----------- | ---------------------------------------------------- |
| **Theme**   | Light, Dark, or Auto (follows your macOS appearance) |

Per-workspace background colors are set separately -- see [Spaces](/spaces).

### Agents

| **Setting**       | **Description**                                                                   |
| ----------------- | --------------------------------------------------------------------------------- |
| **Active agents** | Enable or disable agent runtimes. Disabled agents disappear from the space picker |

### Menu Bar

| **Setting**       | **Description**                           |
| ----------------- | ----------------------------------------- |
| **Menu Bar Icon** | Show the Mains icon in the macOS menu bar |

### Notifications

| **Setting**       | **Description**                                   |
| ----------------- | ------------------------------------------------- |
| **Run Complete**  | Notify when an agent run finishes                 |
| **Tool Approval** | Notify when an agent is waiting for tool approval |

### Software Updates

Mains checks for updates automatically. This section shows the current version and lets you check for, download, and install a new one with progress tracking.

## **Git**

Settings that shape how [git actions](/git-actions) behave.

| **Setting**                  | **Description**                                                                                                    |
| ---------------------------- | ------------------------------------------------------------------------------------------------------------------ |
| **Worktrees**                | Work in an isolated copy of the repo so several tasks run at once. When off, Mains uses the active branch directly |
| **Commit Instructions**      | Appended to commit-message generation prompts -- e.g. *"use conventional commits, keep under 72 chars"*            |
| **PR Template Instructions** | Appended to pull-request generation prompts -- e.g. *"include a test plan, link related issues"*                   |

<Note>
  Both instruction fields can also be set **per project** (**Settings → Projects**). A project's instructions win over the app-level ones.
</Note>

## **Connections**

Manage connected services: see which integrations are active, connect new ones, trigger a manual sync, or revoke access. Connections are grouped by category:

* **Issues** -- [GitHub](/github), [GitLab](/gitlab), [Linear](/linear), [Jira](/jira), [Asana](/asana), [Trello](/trello)
* **Monitoring** -- [Sentry](/sentry)
* **Security** -- [Socket.dev](/dependency-guards)

Credentials are encrypted at rest -- see [Privacy](/privacy).

## **Provider settings**

Each agent runtime has its own section. They're not in the Settings nav: open one from the space picker, or from the customizer on an empty workspace (see [Spaces](/spaces)).

| **Provider** | **Key settings**                                                                                                                                             |
| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Claude**   | Permission mode, structured output, MCP servers, skills, agents, slash commands -- see [Claude configuration](/claude/configuration)                         |
| **Codex**    | Approval policy, sandbox mode, network access, personality, web search, skip git check, structured output -- see [Codex configuration](/codex/configuration) |
| **Copilot**  | Agents and skills -- see [Copilot configuration](/copilot/configuration)                                                                                     |
| **Cursor**   | Mode -- see [Cursor configuration](/cursor/configuration)                                                                                                    |

## **Projects**

Per-project overrides: root path, worktree directory, setup/run/archive scripts, and project-scoped commit and PR instructions. See [Projects](/projects).