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

# Project Config

> .auto/config.yaml — the optional per-project settings singleton, its fixed config/project resource, and what it does (and does not) control today.

`.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.

```yaml .auto/config.yaml theme={null}
# Intentionally empty. There are no project-level settings yet; the file's
# presence is what creates the config/project resource.
```

## 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](/concepts/github-sync) PR plan check on a pull request or the `auto.resources.dry_run` MCP tool — both run the same compile.

<Note>
  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.
</Note>

## Lifecycle

| Action in the repo                   | Effect on the resource                                                             |
| ------------------------------------ | ---------------------------------------------------------------------------------- |
| Add `.auto/config.yaml` (even empty) | Creates `config/project`                                                           |
| Change it                            | Updates `config/project` (invalid keys fail the apply)                             |
| Delete it                            | Archives `config/project` — directory applies prune resources whose files are gone |

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.

## Related pages

* [Resource model](/concepts/resource-model) — how apply, prune, and archive work for every resource kind
* [Agent file](/reference/agent-file) — where per-agent configuration actually lives
* [GitHub Sync](/concepts/github-sync) — the merge-to-apply pipeline that owns this file