# Settings

> Every section and what it controls.

Settings takes over the window. Open it with ⌘, (Ctrl on Linux and Windows) or the gear in the sidebar; the back button or Escape leaves. **Search settings** at the top filters the sections, and it matches what a section is about, the titles of its rows and its name: "tailscale" finds Remote, "island" finds Notifications and "tokens" finds Usage. A search scrolls to the row it matched.

Every row is a card, and only its switch switches: clicking a row's words does not turn it on. The longer half of a row — what it does and what it does not — folds under **How it works**.

## Application

- **General** — opens on **Local by default**, which is a statement rather than a switch: "Projects, conversations and settings are kept on this computer." Then:
  - **On this desktop**: **Open at login**, **Keep devpit in the tray when the window closes**, **Shortcut** (keys that bring devpit forward from anywhere, none until you choose), **Display**, and **Open in** ("The apps offered when you open a project or a worktree somewhere else").
  - **Updates and privacy**: **Automatic updates**, on by default; the **Updates** row, with the version you have and **Check now**; **Error reports**, off unless you turn it on. See [Staying up to date](/docs/updating) and [Where your data lives](/docs/your-data).
- **Notifications** — **Island**, on by default, with how it is drawn on this desktop and, where it would be an ordinary window on Wayland, **Show the island anyway**. **Pause**: quiet for a while or until you resume. **Reminders**, on by default. **Focus mode**: unfinished, and off until you turn it on. See [The island](/docs/island), [Notifications](/docs/notifications), [Reminders](/docs/reminders) and [Focus mode](/docs/focus).
- **Remote** — **Remote**, off until you turn it on, with how to get in and each paired device; **Allow remote MCP (read-only)**; and **Calendar**. See [Remote](/docs/remote).
- **Appearance** — theme: **System**, **Light** or **Dark**. **Terminal contrast**: **None**, **Readable** or **Strong**; until you pick one it follows the ground. The terminal keeps its dark ground in every theme.
  Under **Text**: **Text size** and **Code size** (Small, Default, Large, Larger), for the conversation and for code and every diff; **Contrast**, **Standard** or **More**, which draws secondary text and borders closer to the main text in any theme; and **LaTeX maths**, off by default. Under **Diffs**: **Diff layout**, **Whitespace in diffs**, **Diff colours** and **Files in a diff**. See [Files and changes](/docs/files-and-changes#diff).
- **Keyboard** — every key the window listens for, each one changeable. See [Keyboard shortcuts](/docs/shortcuts).
- **Maintenance** — how hard devpit works in the background and what it keeps. Every default is what devpit did before:
  - **Power saver**, off by default. On, devpit looks at its panes, devpit.app and sync four times less often while nobody is at the window or the machine runs on battery.
  - **Keep logs and run artifacts**: **Never** by default, or 7, 14, 30 or 90 days. Older logs, and older Devflow runs and reviews, go ten minutes after start and every six hours, or at once with **Delete now**, which says how many went and what that freed. Of each card, the newest run stays.
  - **Labs**: **Project agent** and **Canvas**, both on by default. See [The project agent](/docs/project-agent) and [Excalidraw](/docs/excalidraw).
- **Diagnostics** — what devpit itself is running and costing: its processes, with CPU and memory, sorted by memory, with the totals; the checks [`devpit diagnostics`](/docs/devpit-command) prints, each failing one with its fix; and the newest entries of devpit's error log, with where it is. It reads when the pane opens and on **Look again**, never on a timer.
- **About** — the version and platform, and **Open** for the privacy policy, the licence and the open-source notices.

## Workspace

- **Projects** — every project, with **Add project**, and **Open**, **Rename**, **Reveal**, **Open in** and **Remove** on each row. See [Projects](/docs/projects).
- **Worktrees** — where card checkouts are made, which kinds of checkout devpit counts, the **Branch name** pattern and **Branch name for this project**, **Cleanup** of merged ones, and each card's checkout with **Remove**. See [Worktrees](/docs/worktrees).
- **Storage** — where each project's workspace folder lives, `~/.devpit/projects/<name>-<suffix>`, and what is in it. See [Where your data lives](/docs/your-data).
- **Archive** — the open project's archived conversations, each with **Restore**. See [Conversations](/docs/conversations#archive).

## AI capabilities

- **Providers** — **Default agent**: "What a new terminal opens. A plain shell is an answer too." **Agent status hooks**: working, waiting and done on the island, in the sidebar and on a card. **Installed**, with a count of what was detected on this machine, each row opening its [profile](/docs/profiles) editor. **Not on this machine**, listing the rest with a link to each, and a **Refresh** button for after you install one. See [Providers](/docs/providers).
  **Check sign-ins and MCP servers**: every minute, or every 5, 15 or 30 minutes, 5 by default. **Default model**: the model a new chat starts with, for all projects or one (see [For one project](/docs/settings#for-one-project)). A Claude Code profile, opened, has its models, an advisor model and a subagent model; see [Profiles](/docs/profiles#models).
- **Sessions** — **Open the next card on its own**, off by default: when a card is finished or lands in done, the next card of its epic that waited on it opens in a session of its own. **Hand off a full session**. **Chat activity**, the default for the [chat's Activity menu](/docs/chat#how-much-of-the-work-you-see). **Ask before stopping a terminal** (below).
  **Send with**, **Enter** or **⌘Enter**, and **While a turn runs**, **Queue** or **Steer**; see [Chat](/docs/chat#while-the-turn-runs). **Permission mode**: the mode a new chat starts in, for all projects or one.
- **Skills** — the skills your agent CLI has installed, read from its own configuration. See [Skills and MCP](/docs/skills-and-mcp).
- **Channels** — where devpit reaches you away from the window, such as Telegram, and what goes there.
- **Voice** — **Voice messages**: how a recording becomes words — **This machine**, **A service** or **Off**. **Check again** looks for a whisper you just installed, without reopening Settings. See [Chat](/docs/chat#files-and-voice).
- **Devflow** — Devflow's stages, reviewers and setup for each project.
- **Orchestrator** — **Guardrails**: which of an orchestrator's actions wait for you, set for each orchestrator. See [Guardrails](/docs/guardrails).
- **Assistant** — how often the [Assistant mode](/docs/assistant) heartbeat looks, every 5 to 60 minutes, and which of its checks are on.
- **Decisions** — off unless you set it up: what judges evidence against a rubric, with its key.

## Account

- **Account** — who is signed in, and **Sign out**. See [Account](/docs/account).
- **Accounts** — your Claude Code accounts and their limits.
- **Usage** — what your sessions cost, and your plan limits. See [Usage and plan limits](/docs/usage).

## For one project

Three rows have **Applying settings for**, which chooses **All projects** or one project: **Default model** in **Providers**, **Permission mode** in **Sessions** and **Branch name for this project** in **Worktrees**. **All projects** sets this machine's value; a project's value is for that project only. Each row says where the value in use comes from, and a change writes only that one setting.

A repository can carry shared defaults in `.devpit/settings.json`, read from the project's root:

```json
{
  "model": "sonnet",
  "permissionMode": "plan",
  "worktree": { "branchPattern": "feat/{number}-{slug}" }
}
```

A value set for the project wins over the repository's file, which wins over all projects. New chats start with the project's model and permission mode, though a model or mode picked in a conversation still wins and an orchestrator keeps its own. Cards' worktrees take the project's branch name. With nothing set, everything starts as it always did.

The file can ask for **Supervised** (`"manual"`) or **Plan** (`"plan"`), never a mode that asks less: that one is yours to choose. A file that is not valid, is over 64 KB, is not a plain file or leads outside the project is left out whole, and the row says why.

## Ask before stopping a terminal

The question devpit asks before it closes a terminal that is still running something has a **Don't ask again** of its own. Ticking it turns this switch off; turning the switch back on in **Settings → Sessions** brings the question back. See [The terminal](/docs/terminal).
