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

# Settings

> How ADE Settings is organized, a recommended first pass, and the first-run setup that detects your stack.

Settings is where you connect providers, link GitHub and Linear, tune how ADE looks and behaves, and shape how lanes are created. It's organized by the kind of thing you're changing, not by which service backs it.

## The pages

Settings opens on **General**. The sidebar groups the rest by what they belong to: you, the app, the open project, and the machines.

> [card] General
>
> Anything that needs attention, cards for you and this machine, and ADE itself: version, update track, automatic updates, and an update row for every machine.

> [card] You
>
> **Account** (sign-in, connections, your computers) and **Usage** (spend and pacing across your providers and machines).

> [card] App
>
> **Chat**, **Providers** (one list, with a machine picker in its title, and the **Custom** section), **MCP servers**, **ADE MCP**, **Notifications**, **Appearance**, **Behaviour**, and **Apple devices** on macOS.

> [card] Project
>
> **Lanes**, **Agents**, **Storage & cleanup**, **Location**, **Secrets**, and **Integrations** (GitHub, Linear, and Jira) for the open project.

> [card] System
>
> **Machines**, with a page per machine (its load, its **New work** preference, and the work it keeps for chats on other machines), and **Advanced** (the background service, the `ade` command, reports, database copies, and reset).

**Continue chats after restarts** is one setting per machine, in **Settings › Chat › Restarts**. Old Settings links still land on the right page.

> [!NOTE]
>
> A few controls live in the **top bar**, not in Settings: live provider quota windows and the automation budget sit in the **Usage** popup, and phone pairing and multi-device sync sit in the **Sync** popover. **Settings › Usage** is the retrospective view; the Usage popup is the live one.

## First-run setup

When you open a project for the first time, ADE shows a setup dashboard — a single page of status cards rather than a blocking step-by-step wizard. It detects your stack and suggests config so you don't have to write it by hand:

* **Developer tools** — checks for `git` and the GitHub CLI.
* **Stack detection** — looks for `package.json`, `Cargo.toml`, `go.mod`, `pyproject.toml`, a `Makefile`, `docker-compose`, and `.github/workflows/`, then suggests processes, test commands, and stacks.
* **AI runtimes** — a compact band to set up the major provider runtimes.
* **GitHub and Linear** — optional cards for repository auth and Linear connection.
* **Existing worktrees** — import git branches you already have as lanes in one click.

Nothing here blocks you. You can skip any card and re-run setup later.

## Recommended first pass

Only the first step is required to start running agents — the rest unlock GitHub, Linear, and mobile workflows.

**1. Verify one provider**

In **Providers**, make sure at least one of Claude Code, Codex, Cursor, Factory Droid, or OpenCode is green. That's all you need to start a lane chat.

**2. Connect GitHub**

Do this for PR creation, CI state, comments, and merge workflows.

**3. Connect Linear**

Do this if issues should link to lanes, CTO work, and PR updates.

**4. Pair your phone**

From the top-bar **Sync** popover, reveal the pairing PIN to bring agent work and PR activity to iOS.

**5. Watch spend**

Check the top-bar **Usage** popup and set a budget cap before running many agents in parallel.

## Shared vs. local config

ADE splits project configuration into two files: shared, version-controlled team config (`.ade/ade.yaml`) and a per-user, gitignored overlay (`.ade/local.yaml`). Saving shared config triggers a trust confirmation, since shared settings can introduce commands that run on every teammate's machine. Anything with a secret — provider keys, GitHub and Linear tokens — stays in a local encrypted store and is never committed.

> [card] [AI providers](https://ade-app.dev/docs/configuration/ai-providers.md)
>
> Connect each agent, set permission presets, and control cost.

> [card] [Project configuration](https://ade-app.dev/docs/configuration/overview.md)
>
> Where ADE stores local state and what to keep out of Git.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.