# Configuration file

> Every key of _bmad/config.yaml: execution mode, the four checkpoints, the uat block and the swarm budget. Defaults, who reads each key, and what changing it does.

Canonical: https://bmad-plus.rochetta.fr/docs/reference/config-yaml/
Language: en
BMAD+ version: 0.23.1
Documentation reviewed: 2026-10-19
Author: Laurent Rochetta
License: MIT

BMAD+ documentation › [Reference](https://bmad-plus.rochetta.fr/docs/reference/) › Configuration file

`_bmad/config.yaml` is the one file where a project tells BMAD+ how to behave: which language to use, whether agents run one at a time or under the Nexus orchestrator, where the agents must stop and wait for you, how human acceptance recipes are handled, and how many sub-agents a swarm may use. `bmad-plus install` creates it; you may edit it by hand. This page lists every key it writes.

> **Note · Who reads this file** The command line itself reads only a few values: the `swarm` block (validated by `bmad-plus swarm`), five text keys used by `bmad-plus studio`, and `communication_language` for the language of an acceptance page built by `bmad-plus uat`. Everything else is read by the agents: their skill instructions tell them to open this file and follow it. That is why a changed checkpoint takes effect the next time an agent starts a pipeline, with no command to run.

<a id="generated"></a>
## What install writes

**The file after install --yes --lang fr in a folder named demo-app, replayed with the 0.23.0 package. The writer quotes string values with single quotes, and user_name falls back to your system user name, then to Developer**

```yaml
# BMAD+ Project Configuration
# Generated by bmad-plus install

user_name: 'Developer'
communication_language: 'Français'
document_output_language: 'Français'
output_folder: '_bmad-output'
project_name: 'demo-app'
execution_mode: 'manual'
auto_role_activation: true
parallel_execution: true
checkpoints:
  discovery: 'require_approval'
  architecture: 'require_approval'
  story: 'require_approval'
  delivery: 'require_approval'
uat:
  mode: 'advisory'
  granularity: 'delivery'
  environment:
    name: ''
    url: ''
  page_budget:
    max_steps: 15
    max_minutes: 30
  dir: '_bmad-output/uat'
swarm:
  budget: 26
  wave: 10
  media_credits: 'ask'
```

The values for `user_name`, `communication_language` and `project_name` come from the wizard or the folder; the rest are the defaults shown. `uat.environment` holds `name: "TEST"` and the address when you typed a test environment URL in the wizard.

<a id="keys"></a>
## Every key

**Keys of _bmad/config.yaml**

| Key | Default | Read by | Effect |
| --- | --- | --- | --- |
| `user_name` | wizard answer, else your system user name, else `Developer` | CLI (`studio`) and agents | The name agents use to greet you. Must be a non-empty text for `studio`. |
| `communication_language` | `--lang` language name, else your system locale if supported, else `English` | CLI (`studio`, `uat`) and agents | Language agents answer in. `uat build` opens the acceptance page in it. |
| `document_output_language` | same as `communication_language` | CLI (`studio`) and agents | Language of the documents agents write (briefs, PRD, reports). |
| `output_folder` | `_bmad-output` | CLI (`studio`) and agents | Where agents put their deliverables. For `studio`, the path must be relative to the project. |
| `project_name` | name of the project folder | CLI (`studio`) and agents | The project name used in documents. |
| `execution_mode` | `manual` | Agents, through their skill instructions | `manual`: you call the agents. `autopilot`: Nexus runs Discovery, Build and Ship. `hybrid`: autopilot with frequent checkpoints. Set at install with `--mode`. |
| `auto_role_activation` | `true` | Agents, through their skill instructions | `true`: an agent may switch role when the context calls for it, after announcing it. `false`: roles change only when you ask. |
| `parallel_execution` | `true` | Agents, through their skill instructions | `true`: the Parallel Supervisor may run independent tasks side by side. `false`: sequential only. |
| `checkpoints.discovery` | `require_approval` | Agents, through their skill instructions | Stop after the product brief, PRD and UX review. |
| `checkpoints.architecture` | `require_approval` | Agents, through their skill instructions | Stop after the architecture, before any code. |
| `checkpoints.story` | `require_approval`; `notify_only` when installed with `--mode autopilot` | Agents, through their skill instructions | Applied after each completed story. |
| `checkpoints.delivery` | `require_approval` | Agents, through their skill instructions | Applied at the final delivery. With `uat.mode: gate`, it also waits for a passing `uat gate`. |
| `uat.mode` | `advisory` | Agents, through their skill instructions | `advisory`: build and offer the acceptance page, never block. `gate`: the delivery waits for a passing gate. `off`: no recipe, and the delivery report says so. A missing `uat` block means `advisory`. |
| `uat.granularity` | `delivery` | Agents, through their skill instructions | `delivery`: one recipe per delivery. `story`: the page is built and delivered immediately, story by story. |
| `uat.environment` | `name` and `url` empty, or `TEST` and your URL | Agents, through their skill instructions | The test environment the recipe is played on. |
| `uat.page_budget` | `max_steps: 15`, `max_minutes: 30` | Agents, through their skill instructions | Size target for a recipe page: at most this many steps and minutes for the tester. |
| `uat.dir` | `_bmad-output/uat` | Documentation of the location; `bmad-plus uat` takes it from `--dir` | Folder of the recipe specs, pages, results and triage. Its default is the same value. |
| `swarm.budget` | `26` | CLI (`swarm`) and agents | How many sub-agents one swarm run may use before the host must ask you. Integer from 1 to 1000. |
| `swarm.wave` | `10` | CLI (`swarm`) and agents | How many sub-agents are launched together. Integer from 1 to 1000. |
| `swarm.media_credits` | `ask` | CLI (`swarm`) and agents | The only accepted value is `ask`: paid image, video or audio generation is never covered by a budget, the assistant asks every time. |

<a id="checkpoints"></a>
## Checkpoints and execution modes

A checkpoint is a place in the autopilot pipeline where the orchestrator either stops, tells you and moves on, or just moves on. Each of the four keys takes one of three values.

**Checkpoint values**

| Value | Behaviour |
| --- | --- |
| `require_approval` | Stop. Present a reviewable checkpoint and wait. If an earlier authorisation of yours already covers the concrete next action, it is not asked again. An outside notification needs a configured channel and your authorisation. |
| `notify_only` | Report progress in the session and continue. |
| `auto` | Continue automatically and log it for the audit trail. |

> **Note · Installing with --mode autopilot** The only checkpoint that depends on the mode at install time is `story`: it is written as `notify_only` for `autopilot` and as `require_approval` otherwise. Later edits of `execution_mode` do not rewrite the checkpoints; change them yourself.

<a id="example-cli-config-autopilot-delivery-only"></a>
### Autopilot that only stops at delivery

You trust the pipeline up to the finished build and want to approve only what ships.

**In your AI assistant**

```text
In _bmad/config.yaml, set execution_mode to autopilot, set the discovery, architecture and story checkpoints to notify_only and keep delivery on require_approval. Then show me the edited block.
```

**What you should get** The assistant edits the file so that it reads `execution_mode: autopilot` and the checkpoints `discovery`, `architecture` and `story` are `notify_only`, `delivery` is `require_approval`. At the next `autopilot`, Nexus reports at the first three points and keeps going, and stops at delivery with a checkpoint to review.

<a id="swarm-block"></a>
## The swarm block

The `swarm` block is the one part the CLI enforces. A missing block, or a missing key, means the defaults: 26 sub-agents per run, 10 per wave. When `bmad-plus swarm init` is asked for more units than `swarm.budget` and `--approved` is absent, it writes nothing and exits with code 2, so a human decides. Paid media generation is outside any budget.

<a id="example-cli-config-raise-swarm-budget"></a>
### Raise the swarm budget to 50

A panel of 30 simulated buyers was refused with “needs approval” because the budget is 26, and you decide to accept panels up to 50 without asking each time.

**In your AI assistant**

```text
In _bmad/config.yaml set swarm.budget to 50 and leave wave and media_credits as they are. Then re-run the same swarm init without --approved.
```

**What you should get** Because 30 is no longer above the budget, `init` does not stop with exit code 2: it creates the run and prints the panel line (for example “panel of 30 units, budget 50”). A request for 60 units would still be refused until you pass `--approved`.

<a id="reinstall"></a>
## How install treats an existing file

- Existing keys win: running `install` again never overwrites a value you changed.
- Missing keys are added with their defaults, including missing keys inside a block such as `uat` or `swarm`. This is how a project installed with an older version gains the newer blocks.
- Answers you give explicitly replace the stored value: the wizard fields (name, communication language, execution mode), `--mode`, and a test environment URL.
- When anything changes, the file is rewritten by a YAML writer under the header “BMAD+ Project Configuration”. Comments you added by hand are not kept in that case.
- If the file is not a YAML mapping, install leaves it untouched and warns: “_bmad/config.yaml could not be parsed; it was left unchanged.”
- `uninstall` keeps this file, because it holds your settings.

<a id="errors"></a>
## Errors you can hit

**Configuration errors reported by the CLI**

| Message | Cause | What to do |
| --- | --- | --- |
| `_bmad/config.yaml: swarm.budget must be an integer from 1 to 1000.` | `budget` (or `wave`, same message with its name) is not a whole number in range. | Write a plain integer, for example `budget: 50`. |
| `_bmad/config.yaml: swarm.media_credits must be "ask".` | Any other value was written. | Set `media_credits: "ask"` or delete the line. |
| `_bmad/config.yaml: swarm has an unknown key "<name>".` | A key other than `budget`, `wave`, `media_credits` is in the block. | Remove it or fix the spelling. |
| `_bmad/config.yaml is not valid YAML: …` | The file cannot be parsed. | Fix the indentation or quoting shown in the message. |
| `_bmad/config.yaml: user_name must be a nonempty string` | `studio` requires its five text keys (`user_name`, `communication_language`, `document_output_language`, `output_folder`, `project_name`) to be non-empty strings when present. | Give the key a text value or delete it to fall back to the default. |

**See also**

- [install: how the file is created](https://bmad-plus.rochetta.fr/docs/reference/cli-install/)
- [swarm: budget, waves and approval](https://bmad-plus.rochetta.fr/docs/reference/cli-swarm/)
- [uat: acceptance recipes](https://bmad-plus.rochetta.fr/docs/reference/cli-uat/)
- [Project layout](https://bmad-plus.rochetta.fr/docs/reference/project-layout/)
- [Troubleshooting](https://bmad-plus.rochetta.fr/docs/faq/troubleshooting/)

[BMAD+ documentation](https://bmad-plus.rochetta.fr/docs/) · [Reference](https://bmad-plus.rochetta.fr/docs/reference/)

[Source on GitHub](https://github.com/lrochetta/BMAD-PLUS)