Configuration overview

ADE keeps project state local. Everything ADE creates for a project lives under .ade/ at the repository root, alongside your source tree but outside Git’s control. Your code stays under normal version control; ADE’s runtime bookkeeping stays out of it.

.ade/
  ade.db        # lanes, sessions, PR mappings, proof metadata, settings
  ade.yaml      # shared, version-controlled team config
  local.yaml    # per-user overrides (gitignored)
  worktrees/    # managed lane worktrees (one directory per lane)
  artifacts/    # proof artifacts (screenshots, recordings, traces)
  cache/        # derived data ADE can rebuild
  secrets/      # encrypted, machine-local credentials

Shared vs. local config

ADE splits configuration into two files, both merged into one effective config at read time:

File	Scope	In Git?	Holds
`.ade/ade.yaml`	Shared	Committed	Team-wide processes, stacks, tests, lane templates, automations, AI mode, and provider/Linear preferences.
`.ade/local.yaml`	Local	Gitignored	Personal overrides: ports, env vars, machine-specific paths, local-only processes.

Keep secrets and machine-specific paths in local config. Shared config is visible to the whole team, so anything in it ships to every teammate.

What stays local

Area	Contains
Database (`ade.db`)	Lanes, sessions, PR mappings, proof metadata, and settings.
Worktrees	The isolated working copy for each lane.
Artifacts	Proof captures — screenshots, recordings, and traces.
Secrets	Encrypted, machine-local credentials.
Cache	Derived data ADE can regenerate on demand.

Trust model

Commands saved as shared project defaults can run on developer machines. ADE treats those definitions as sensitive: when the shared config changes, it requires a local trust confirmation before the new version can spawn processes. Review such changes the same way you’d review a CI script or Dockerfile. Local config isn’t trust-gated — you only need to trust your own overrides.

What’s committed, and what isn’t

ADE manages this for you. It writes a .ade/.gitignore that ignores everything under .ade/ by default and allowlists only the authored files meant to travel with the repo — ade.yaml, lane templates, skills, and project icons. Runtime files (the database, worktrees, artifacts, cache, and secrets) stay out of Git automatically, so you don’t have to maintain ignore rules by hand.

Never put provider keys, tokens, or other secrets in .ade/ade.yaml or any committed file. Secrets belong in the local encrypted store or .ade/local.yaml, both of which stay off the shared path.

Permissions

Lane scope, provider modes, and the shared-config trust model.

Settings

Configure the app from the UI.

Settings

AI Connections

For developers

Configuration overview

Shared vs. local config

What stays local

Trust model

What’s committed, and what isn’t

Permissions

Settings

​Shared vs. local config

​What stays local

​Trust model

​What’s committed, and what isn’t

Permissions

Settings

Shared vs. local config

What stays local

Trust model

What’s committed, and what isn’t