Skip to main content
.auto/config.yaml is the optional project settings file. It carries a bare spec — no kind/metadata envelope — and compiles to exactly one resource with a fixed identity: kind config, name project. It applies and prunes like any other resource, so the presence of the file and the presence of the resource stay in lockstep.

​
The file

  • Location: .auto/config.yaml (or .yml) at the root of the .auto/ directory — not under .auto/agents/.
  • At most one: a repo carrying both config.yaml and config.yml fails the apply with an error naming both paths.
  • Exactly one YAML document: a multi-document file is rejected.
  • An empty file is valid — it applies the empty singleton, which is the entire useful surface today.
.auto/config.yaml

​
What it controls

Nothing, currently. The spec schema is a strict empty object: there are no project-level settings today. The file and its resource exist so that when project-level settings do land, they have a stable home with apply/prune/diff semantics already in place. Strictness is deliberate. Any key — including keys that existed in earlier versions, like the removed defaultAgent selector — fails the apply loudly (Invalid project config .auto/config.yaml: …) instead of being silently ignored, so a stale config can never masquerade as still doing something. The failure surfaces through whichever apply path you used: the GitHub Sync PR plan check on a pull request or the auto.resources.dry_run MCP tool — both run the same compile.
The project’s Default agent is not configured here. Every project gets a permanent built-in default agent, and a project with no authored default file still gets that resource. Customize it by authoring .auto/agents/default.yaml; your fields and imports merge over Auto’s built-in base.

​
Lifecycle

Because the resource name is fixed, a project carries at most one config resource, and the plan comment on a sync PR shows it under the same create/update/delete groups as agents.
  • Resource model — how apply, prune, and archive work for every resource kind
  • Agent file — where per-agent configuration actually lives
  • GitHub Sync — the merge-to-apply pipeline that owns this file