Settings - ADE

Opening Settings

Access Settings from anywhere in ADE:

Keyboard shortcut: Cmd+,
Sidebar: Click the gear icon (⚙) at the bottom of the left sidebar
Menu bar: ADE → Preferences

Settings are organized into twelve sections in the left navigation panel. Changes in most sections take effect immediately — no restart required. Exceptions are noted in the relevant section below.

General

Project identity, theme, terminal preferences.

AI Routing

Per-role models and context management.

Context

Context doc generation and auto-refresh.

Budget & Usage

Caps, alerts, and spend graphs.

AI Providers

API keys and default models per provider.

Integrations

GitHub and Linear.

Computer Use

Backend selection and proof requirements.

CTO

Heartbeat, delegation, memory retention.

Automations

Global automation master switch.

Permissions

File, command, git, and network policy.

Notifications

Native, in-app, and mobile push delivery.

Mobile Push

iOS push notifications for agents.

Diagnostics

Runtime health and diagnostics dashboard.

Developer

Logs, DevTools, and database inspector.

General

Basic project identity and application-level preferences.

Setting	Description	Default
Project name	Display name shown in ADE’s title bar	Derived from repository folder name
Project description	Short description shown on Project Home	Empty
Default working directory	Root directory for terminal sessions	Repository root
Theme	UI color scheme	Default Dark
Auto-update	Whether ADE checks for and installs updates automatically	On
Beta channel	Opt in to receive pre-release builds	Off
Telemetry	Anonymous usage metrics (no PII, no source code)	Opt-in prompt on first launch

Terminal Preferences

Customize terminal rendering for all sessions (interactive, managed, and agent):

Setting	Range	Default
Font size	10–24 px	13 px
Line height	1.0–2.0	1.2
Scrollback	1,000–30,000 lines	10,000

Changes take effect immediately on all open terminal sessions without restart.

Themes

ADE ships with six themes selectable without restart:

Default Dark

ADE’s standard dark theme — dark greys with green accent colors.

Default Light

Light mode with the same green accent palette.

Monokai

High-contrast dark theme with the classic Monokai color palette.

Solarized Dark

Warm dark tones from the Solarized palette.

Solarized Light

Warm light tones from the Solarized palette.

One Dark

Atom-inspired dark theme with cool grey tones.

AI Routing

Control which model each agent role uses, and how ADE manages context windows.

Per-Role Model Overrides

ADE’s default model applies to all agents unless you set role-specific overrides here.

Role	Description	Recommended Model
Orchestrator	Mission planning and worker coordination	`claude-opus-4-7`
Worker	Mission execution tasks	`claude-sonnet-4-6`
Validator	Mission validation and review	`claude-sonnet-4-6`
Automation	Event-driven automation runs	`claude-haiku-4-5`
Chat	Interactive chat sessions	`claude-sonnet-4-6`
CTO	Project-level memory and delegation	`claude-opus-4-7`

Routing automation runs to claude-haiku-4-5 while keeping claude-opus-4-7 for mission planning is the single most impactful cost optimization for users running frequent automations. Most PR-review and routine triage tasks do not require Opus-level reasoning.

Context Management

Setting	Description	Default
Auto-compaction threshold	Percentage of context window used before compaction triggers	70%
Compaction strategy	`summarize` (quality-preserving) or `truncate` (fastest)	summarize
Preserve system prompt	Always keep the system prompt in full during compaction	On
Context warning threshold	Show a usage indicator in the chat header above this percentage	60%

Response Streaming

Setting	Description	Default
Stream responses	Show tokens as they arrive (vs. waiting for full response)	On
Streaming buffer delay	Milliseconds between UI render updates during streaming	16ms

Context

Settings for context doc generation and refresh behavior. Context docs (PRD, architecture overview) are synthesized from your codebase and injected into agent sessions as project-level context.

Setting	Description	Default
Generation model	AI model used to generate context docs	`claude-sonnet-4-6`
Reasoning effort	Depth of analysis during generation	Default (model decides)
Auto-refresh events	Which project events trigger automatic doc regeneration	On PR create, On mission start

Auto-Refresh Events

Toggle individual events that trigger a context doc regeneration:

On session end — regenerate when a terminal/agent session ends
On commit — regenerate when a commit is created
On PR create — regenerate when a pull request is created or updated
On PR land — regenerate when a pull request is merged
On mission start — regenerate when a mission launches
On mission end — regenerate when a mission completes
On lane create — regenerate when a new lane is created

Preferences are saved automatically and persist across sessions.

Budget & Usage

Track and control AI spending across all agents and providers.

Budget Caps

Setting	Description	Default
Per-session cap	Maximum USD per chat session	$1.00
Per-mission cap	Maximum USD across all workers in a single mission	$10.00
Per-automation cap	Maximum USD per automation trigger	$0.50
Monthly total cap	Hard ceiling across all providers, agents, and sessions	$100.00

The monthly cap is a hard stop. Once reached, all agent activity (chat, missions, automations, CTO heartbeats) pauses until either the cap is raised in Settings → Budget or the calendar month rolls over. ADE sends a notification when you reach 80% and again at 100% of the monthly cap.

Alert Thresholds

Configure when ADE notifies you of approaching budget limits:

Session warning: Alert at 80% of per-session cap (default on)
Mission warning: Alert at 80% of per-mission cap (default on)
Monthly warning: Alert at 80% and 95% of monthly cap (default on)

Usage Graphs

The usage panel shows three graph views, each switchable between bar and line charts:

Daily: Per-day spend for the last 30 days, broken down by provider
Weekly: Per-week totals for the last 12 weeks, broken down by agent role
Monthly: Per-month totals for the last 12 months, broken down by lane

Click any bar segment to drill into the individual sessions or missions that contributed to that spend.

AI Providers

Manage API keys for all configured providers. This section is a GUI layer over local.secret.yaml. Changes saved here write directly to that file. For full provider setup instructions, see AI Providers.

Action	How
Add API key	Click Add Key next to the provider, enter the key value
Rotate key	Click Rotate — enter the new key. ADE swaps the key in memory immediately.
Revoke key	Click Revoke — ADE removes the key from `local.secret.yaml` and memory. Agents using that provider will fail until a new key is added.
Test connection	Click Test Connection — ADE sends a minimal request and reports success or the error message
Set default model	Dropdown per provider — writes to `ade.yaml` (requires SHA re-approval if other fields changed)

Integrations

GitHub

ADE uses GitHub OAuth for PR management. A GitHub token can also be supplied in local.secret.yaml for automation workflows that run without an interactive login.

Setting	Description
OAuth connection	Connect or disconnect your GitHub account
Organization access	Manage which GitHub orgs ADE can access
Default branch	Branch ADE opens PRs against (default: `main`)
PR auto-link	Automatically link PRs to ADE missions and lanes when the PR branch matches a lane
Draft PRs by default	Create PRs as drafts until explicitly marked ready

Linear

ADE connects to Linear for bidirectional issue sync. Configure in Settings → Integrations → Linear.

Setting	Description
API key	Linear API key (stored in `local.secret.yaml`)
Sync direction	`bidirectional`, `read-only` (ADE reads Linear), `disabled`
Default team	Linear team for issue creation
Label mappings	Map ADE mission states to Linear issue labels
Issue → Lane auto-create	Automatically create a lane when a Linear issue is assigned to you

Computer Use

Configure which computer-use backend ADE uses for agent-driven browser and desktop automation.

Setting	Description	Default
Backend	`ghost-os`, `agent-browser`, or `ade-local`	`ade-local`
Connection URL	URL for Ghost OS or remote backends	—
Auto-connect on launch	Connect to the backend when ADE starts	On
Default proof requirements	Which action types require screenshot proof	Screenshots for all write actions
Proof storage location	Where captured screenshots and traces are saved	`.ade/artifacts/computer-use/`

The capability matrix at the bottom of this section shows which features each backend supports (screenshots, video recording, DOM access, file download interception, etc.). For full computer use documentation, see Computer Use.

CTO

Settings for the always-on CTO agent that monitors your project and manages workers.

Setting	Description	Default
CTO enabled	Enable or disable the CTO agent entirely	On
Heartbeat interval	How often the CTO runs its check-in loop	15 minutes
Default worker budget	USD budget allocated to each worker the CTO spawns	$2.00
Memory retention	How long to retain project memory entries before summarizing	30 days
Linear sync	`bidirectional`, `read-only`, or `disabled`	bidirectional
Auto-delegation	Allow CTO to spawn workers without asking for approval	Off
Auto-delegation threshold	Only auto-delegate tasks with estimated cost below this value	$1.00

The heartbeat interval controls how frequently the CTO agent wakes up to review open issues, pending missions, and project health. A shorter interval (e.g., 1 minute) gives more responsive CTO behavior but increases AI spend. For most projects, 15 minutes is the right balance.

Automations

Global controls for the automation system.

Setting	Description	Default
Automations enabled	Master switch for all automation rules	On
View all automations	Link to the Automations tab	—

Permissions

High-level controls for what agents are allowed to do. For the full security model, see Permissions.

File Path Restrictions

Configure which filesystem paths agents can read and write:

Allowed paths: Glob patterns. Agents can only access files matching these patterns. Empty = all paths accessible (within the worktree).
Blocked paths: Agents can never access files matching these patterns, regardless of allowedPaths.

Terminal Command Policy

Setting	Description
Command allow list	Agents may only run commands matching these patterns. Empty = all commands allowed.
Command block list	Agents may never run commands matching these patterns. Takes precedence over allow list.
Ask-first mode	Agents must request approval before running commands not on the allow list

Git Restrictions

Setting	Description	Default
Protected branches	Regex patterns for branches agents cannot push to	`main`, `master`, `production`
Allow force push	Whether agents can run `git push --force`	Off (always)
Require commit message template	Validate agent commits against a message format	Off

Network Access

Setting	Description	Default
Network policy	`allow-all`, `allow-list`, or `block-list`	allow-all
Allowed domains	Domains agents can reach (allow-list mode only)	—
Blocked domains	Domains agents can never reach (block-list mode only)	—

Notifications

Control how and when ADE notifies you of important events.

Event	macOS notification	In-app banner	Mobile push
Mission complete	Configurable	Always	Configurable
Mission failed	Configurable	Always	Configurable
Budget warning (80%)	Configurable	Always	Off
Budget cap reached	Always on	Always	Configurable
Conflict detected	Configurable	Configurable	Off
PR status change	Configurable	Configurable	Configurable
Automation triggered	Off	Configurable	Off
Automation completed	Configurable	Off	Configurable
CTO delegation request	Always on	Always on	Configurable
Intervention required	Configurable	Always	Always on

Mobile Push

ADE can send push notifications to your iPhone when agents need input or complete tasks, so you do not have to keep the desktop app in the foreground to stay aware of progress.

Setup

Open Settings → Mobile Push

Navigate to Settings → Notifications → Mobile Push.

Scan the QR code on your iPhone

Open the ADE iOS app and scan the registration QR code shown in the panel. The device is registered to your ADE install within a few seconds.

Choose which events trigger a push

Toggle individual event types. The most useful defaults: mission complete, mission failed, and intervention required (agent needs your input).

You can register multiple iOS devices. Each device receives the same notifications. Devices are listed in the Mobile Push panel with their registration date and last-received timestamp. Tap Remove next to any device to deregister it.

Diagnostics

The diagnostics dashboard (Settings → Diagnostics) gives a live view of ADE’s internal runtime health.

Panel	What it shows
Provider status	Connection state and last response time for each configured AI provider
Lane runtime	Process state, port lease status, and env overlay summary for each active lane
IPC health	Recent IPC error counts and last-seen timestamps per channel
ADE CLI probe	Whether the CLI readiness probe last passed or failed, with the error message if it failed
Sync status	Device registry, last sync timestamp, and any pending sync operations

Use the diagnostics panel before filing a bug report — the summary output can be copied directly from the panel.

Developer

Settings for debugging, diagnostics, and low-level access.

Setting	Description	Default
Log level	`error`, `warn`, `info`, `debug`, `verbose`	`info`
Log file location	Where ADE writes its log files	`~/Library/Logs/ADE/`
Open DevTools	Opens Electron DevTools for the renderer process	—
RPC debug mode	Enables verbose JSON-RPC logging for all ADE RPC calls	Off
Database inspector	Opens a read-only browser of ADE’s SQLite database	—
Reset to defaults	Resets all settings to factory defaults (does not affect `local.secret.yaml`)	—

verbose log level logs every ADE RPC tool call including parameters. Do not use verbose logging in production environments — it may produce large log files and can expose non-secret parameters in plaintext. API keys are always redacted regardless of log level.

Recommended Settings by Use Case

Solo Developer
Small Team
Power User

Prioritize speed and cost efficiency:

Default model: claude-sonnet-4-6
Orchestrator model: claude-opus-4-7
Automation model: claude-haiku-4-5
Per-session budget: $2.00
Monthly cap: $50.00
CTO heartbeat: 15 minutes
Notifications: Mission complete + Budget warning

Emphasize observability and shared standards:

Commit ade.yaml with agreed model defaults and budget caps
Each developer maintains their own local.yaml with personal model preferences
Enable PR auto-link in GitHub integration
Enable bidirectional Linear sync
Turn on Ask-first mode for terminal commands in Permissions
Set CTO auto-delegation to Off (manual approval for worker spawns)

Settings That Should Be Team-Shared vs. Personal

Setting	Shared in `ade.yaml`	Personal in `local.yaml`
Default AI model	Yes	Override per-machine
Budget caps	Yes (defaults)	Override per-machine
Lane profiles	Yes	No
Automation definitions	Yes	No
Process definitions	Yes	No
Test suite config	Yes	No
Theme	No	Yes
Editor font size	No	Yes
Terminal shell	No	Yes
Notification preferences	No	Yes
API keys	Never	In `local.secret.yaml`

What’s Next

AI Providers

Deep dive into configuring Anthropic, OpenAI, OpenRouter, and local models.

Permissions

Understand the full trust boundary model and configure per-agent access rules.

Configuration Overview

Review the .ade/ directory structure and the three config file layers.

Settings Reference

Project Configuration

Computer Use

AI Tool Integrations

Documentation Index

​Opening Settings

General

AI Routing

Context

Budget & Usage

AI Providers

Integrations

Computer Use

CTO

Automations

Permissions

Notifications

Mobile Push

Diagnostics

Developer

​General

​Terminal Preferences

​Themes

Default Dark

Default Light

Monokai

Solarized Dark

Solarized Light

One Dark

​AI Routing

​Per-Role Model Overrides

​Context Management

​Response Streaming

​Context

​Auto-Refresh Events

​Budget & Usage

​Budget Caps

​Alert Thresholds

​Usage Graphs

​AI Providers

​Integrations

​GitHub

​Linear

​Computer Use

​CTO

​Automations

​Permissions

​File Path Restrictions

​Terminal Command Policy

​Git Restrictions

​Network Access

​Notifications

​Mobile Push

​Setup

​Diagnostics

​Developer

​Recommended Settings by Use Case

​Settings That Should Be Team-Shared vs. Personal

​What’s Next

AI Providers

Permissions

Configuration Overview

Opening Settings

General

Terminal Preferences

Themes

AI Routing

Per-Role Model Overrides

Context Management

Response Streaming

Context

Auto-Refresh Events

Budget & Usage

Budget Caps

Alert Thresholds

Usage Graphs

AI Providers

Integrations

GitHub

Linear

Computer Use

CTO

Automations

Permissions

File Path Restrictions

Terminal Command Policy

Git Restrictions

Network Access

Notifications

Mobile Push

Setup

Diagnostics

Developer

Recommended Settings by Use Case

Settings That Should Be Team-Shared vs. Personal

What’s Next