Configuration Overview

ADE stores project configuration in a .ade/ directory at your repository root. Shared team settings, personal overrides, and local secret references stay separated by a SHA-based trust model.

The .ade/ Directory

ADE initializes a .ade/ directory at the project root on first open. It is the single source of truth for all ADE configuration, runtime artifacts, and worktree management.

.ade/
  ade.yaml              # Shared team config — commit this to git
  local.yaml            # Personal preferences — gitignored
  local.secret.yaml     # Automation secret references — ALWAYS gitignored
  secrets/              # Encrypted machine-local credentials and tokens
  worktrees/            # Git worktrees for each lane (auto-managed by ADE)
  artifacts/
    packs/              # Compatibility snapshots and audit artifacts
    checkpoints/        # Session boundary snapshots
    sessions/           # Agent session transcripts
    audit.log           # Append-only audit trail

Never commit local.yaml or local.secret.yaml to git. ADE automatically adds both to .gitignore on initialization, but verify this if you manage .gitignore manually. Committing secrets is irreversible once pushed to a remote.

The worktrees/ and artifacts/ subdirectories are ADE-managed. Do not edit them directly.

---

Configuration Layering

ADE resolves project configuration from two files, then reads secret references separately when a service needs them.

ade.yaml

Shared team config. Committed to git. Contains project defaults, AI model settings, lane templates, automation definitions, and trusted command definitions. Every team member reads this file.

local.yaml

Personal overrides. Gitignored. Overrides the same parsed config fields in ade.yaml for your machine only.

local.secret.yaml

Secret references. Always gitignored. Used by automation/webhook services when config points at a secretRef. AI provider keys saved from Settings live in the encrypted key store under .ade/secrets or the OS credential store, not in committed config.

When resolving project config, ADE loads ade.yaml first and overlays local.yaml for that machine only. local.secret.yaml is not a third config layer; services read it only when a secretRef points at a path inside that file.

---

The Trust Model (SHA-Based Approval)

ade.yaml can contain command definitions (process startup commands, automation executors, test suite runners). Because this file is committed to git, a malicious change in a PR could introduce arbitrary commands that run on your machine. ADE prevents this with a SHA-based approval gate.

1. ADE detects a change

   Whenever ade.yaml changes — from a git pull, a teammate’s commit landing via fetch, or a direct edit — ADE immediately detects the difference.

2. ADE shows a diff and pauses

   ADE presents a structured diff of the changed fields and suspends execution of any commands defined in the new version. No new processes start, no automations trigger, no agents run commands from the updated config.

3. You review and approve

   Review the diff in the approval dialog (Settings → Config → Pending Approval, or the banner that appears automatically). If the changes are expected and safe, click Approve.

4. ADE records the approved SHA

   The SHA of the approved ade.yaml is recorded in local ADE state. Commands from this version of the config are now permitted to execute.

The approved SHA is machine-specific. If two developers need to approve the same change, each must approve it on their own machine. This is intentional — one person’s trust cannot be delegated to another.

To re-approve the currently loaded config (e.g., after a manual edit): Settings → Config → Re-approve current config.

---

ade.yaml — Full Schema Reference

Shared team config — commit this file. Every field is optional.

# .ade/ade.yaml

version: 1
project:
  iconPath: null

# ── AI Defaults ───────────────────────────────────────────────────────────────
ai:
  defaultModel: "claude-sonnet-4-6"
  budgets:
    commit_messages:
      dailyLimit: 20
    pr_descriptions:
      dailyLimit: 10

# ── Process Definitions ───────────────────────────────────────────────────────
processGroups:
  - id: "app"
    name: "App"

processes:
  - id: "frontend"
    name: "Frontend"
    command: ["npm", "run", "dev"]
    cwd: "."
    groupIds: ["app"]
    readiness:
      type: "port"
      port: 3000

# ── Test Suites ───────────────────────────────────────────────────────────────
testSuites:
  - id: "unit"
    name: "Unit Tests"
    command: ["npm", "test"]
    cwd: "."
    timeoutMs: 600000
    tags: ["unit"]

# ── Lane Templates ────────────────────────────────────────────────────────────
laneTemplates:
  - id: "web-feature"
    name: "Web feature"
    description: "Copy local env and install dependencies for a web lane."
    envFiles:
      - source: ".env.example"
        dest: ".env"
    dependencies:
      - command: ["npm", "install"]
    envVars:
      NODE_ENV: "development"

defaultLaneTemplate: "web-feature"

# ── Automation Definitions ────────────────────────────────────────────────────
automations:
  - id: "pr-reviewer"
    name: "PR Reviewer"
    mode: "review"
    enabled: true
    trigger:
      type: "github.pr_opened"
    execution:
      kind: "agent-session"
      laneMode: "reuse"
    executor:
      mode: "automation-bot"
    prompt: "Review this PR for code quality, security issues, and adherence to project conventions."
    toolPalette: ["repo", "git", "github", "tests"]

ai — AI defaults

ai.defaultModel sets the default runtime model. ai.budgets is a map keyed by ADE feature (commit_messages, pr_descriptions, terminal_summaries, etc.); each entry currently supports dailyLimit.

processes — Dev server definitions

Process definitions describe how to start development servers. Use id, command arrays, cwd, optional groupIds, and optional readiness checks. processGroups defines the visual groups referenced by groupIds.

testSuites — Test runner config

Test suites use id, command arrays, cwd, optional timeoutMs, and tags. ADE uses these definitions when agents or automations need a known validation command.

laneTemplates — Lane environment templates

Lane templates are top-level laneTemplates entries. defaultLaneTemplate names the template applied by default. Templates can copy env files, install dependencies, define mount points, copy paths, reserve a port range, and set lane env vars.

automations — Event-driven automation rules

Automation definitions are shared team-wide. Each automation has an id, triggers, an execution mode, an executor object, and optional built-in actions such as agent-session, run-tests, run-command, and ade-action. See Automations for the full automation reference.

Config trust — Managed by ADE

ADE hashes ade.yaml and stores the approved shared hash in local ADE state. There is no trust.approvedSha field to author in project config.

---

local.yaml — Full Schema Reference

Personal overrides — gitignored, never shared. Uses the same parsed schema as ade.yaml and overrides shared values for your machine only.

# .ade/local.yaml

ai:
  defaultModel: "claude-sonnet-4-6"
  chat:
    defaultProvider: "last_used"
    sendOnEnter: true
    codexSandbox: "workspace-write"

git:
  autoRebaseOnHeadChange: false

github:
  prPollingIntervalSeconds: 60

---

local.secret.yaml — Full Schema Reference

Automation secret values addressed by secretRef. Always gitignored. Only main-process services read this file; the renderer UI never has access to its raw contents.

# .ade/local.secret.yaml

webhooks:
  github: "${env:GITHUB_WEBHOOK_SECRET}"
  linear: "${env:LINEAR_WEBHOOK_SECRET}"

release:
  npmToken: "${env:NPM_TOKEN}"

local.secret.yaml must never be committed to git. ADE adds it to .gitignore automatically, but also add it manually if your project has nested .gitignore files. Run git check-ignore -v .ade/local.secret.yaml to verify it is excluded. Store AI provider API keys with Settings → AI Providers whenever possible; ADE persists those credentials in the OS credential store or encrypted .ade/secrets/api-keys.v1.bin.

---

Hot-Reload Behavior

ADE watches all three config files using filesystem events (debounced 500ms). Changes take effect without restarting ADE.

File	What happens on change
ade.yaml	ADE detects the change, diffs against the approved SHA, and suspends commands until you approve the new version
local.yaml	Parsed project-config overrides, such as ai, git, github, lane templates, and automations, are reloaded for this machine
local.secret.yaml	Automation secret refs reload for services that watch or request secrets; provider keys managed in Settings use the encrypted credential store

If you update a value in local.secret.yaml, automation code that resolves the related secretRef uses the new value on its next read. In-flight work keeps the value it already loaded.

---

Best Practices

What to commit

Commit ade.yaml. It contains the team’s shared AI model defaults, lane templates, automation definitions, test suite config, and process definitions. Committing it ensures all team members use the same baseline configuration.

Do not commit local.yaml or local.secret.yaml. ADE’s .gitignore entries cover these, but double-check when initializing new repositories.

Rotating API keys

To rotate an AI provider API key, use Settings → AI Providers. ADE writes the new value to the encrypted credential store and uses it on the next provider call. Do not put provider keys in committed ade.yaml.

Never commit the old or new key values to git during rotation. If a key was accidentally committed, revoke it at the provider immediately regardless of whether you have since removed it from the file.

Reviewing ade.yaml changes from teammates

When you git pull and ade.yaml has changed, ADE shows the approval dialog before resuming any command execution. Read the diff carefully — pay particular attention to changes in automations[*].executor, processes[*].command, and testSuites[*].command. These fields define commands that will run on your machine.

Using environment variables instead of file values

For CI environments or machines where you cannot write credential-store values, provider runtimes can read standard provider variables such as ANTHROPIC_API_KEY, OPENAI_API_KEY, OPENROUTER_API_KEY, GOOGLE_API_KEY, and CURSOR_API_KEY. Automation secrets can also reference environment values from local.secret.yaml with ${env:NAME}.

Multiple projects on the same machine

Each project has its own .ade/ directory with its own local.yaml and local.secret.yaml. You can use different API keys or different preferred models for different projects. Settings in one project’s .ade/ never affect another project.

---

What’s Next

AI Providers

Configure Anthropic, OpenAI, OpenRouter, and local models. Set budgets and context preferences.

Settings

Full reference for every setting in ADE’s Settings page.

Permissions

Understand ADE’s trust boundary model and configure agent permissions.