# autoconfig

> Bootstrap BMAD+ in an existing repository or an empty folder: it detects the stack, scores project health, recommends packs, installs them and seeds the project memory.

Canonical: https://bmad-plus.rochetta.fr/docs/reference/cli-autoconfig/
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/) › autoconfig

`autoconfig` is the one-command start for a project you have not set up yet. Instead of choosing packs yourself, you let BMAD+ look at the folder, recommend a set of packs, run `install` with them and write a first project context into the memory. Use it when you land in an unfamiliar repository or when you do not yet know which packs you need. If you already know what you want, `install` gives you full control.

A pack is an installable bundle of agents and skills (see the packs section). A project is treated as existing when its folder holds at least one visible entry, meaning one whose name does not start with a dot. Otherwise it is treated as new.

<a id="synopsis"></a>
## Synopsis

**In your project terminal**

```sh
npx bmad-plus autoconfig [-d <path>] [-l <code>] [-y]
```

**Options of autoconfig**

| Flag | Argument | Default | What it does |
| --- | --- | --- | --- |
| `-d, --directory <path>` | path | current directory | Project to analyse and install into. |
| `-l, --lang <code>` | en, fr, es, de, pt-br, ru, zh, he, ja, it | en | Language handed to the installer it runs. autoconfig’s own messages stay in English. |
| `-y, --yes` | none | off | Existing project only: skip the “Install N recommended packs?” confirmation. It does not skip the new-project questions. |

> **Warning · --yes does not make a new project unattended** In an empty folder the wizard always asks two questions (project type, one-sentence description), whatever `--yes` says. Run it in a terminal you can answer in.

<a id="how-it-decides"></a>
## How it decides

<a id="existing-project"></a>
### Existing project

It reads the folder, shows a short analysis (stack, structure, a health bar, whether BMAD+ or an instruction file is already there), lists the recommended packs with a reason each, asks for confirmation (unless `--yes`), installs, and prints up to five next steps phrased as prompts for an agent.

**Which packs are recommended**

| Pack | Recommended when |
| --- | --- |
| `core`, `memory` | Always. |
| `dev-studio` | There is no `docs`, `doc` or `documentation` folder, or the folder has more than five visible top-level directories (`node_modules` not counted). |
| `shield` | A `.github`, `.gitlab-ci` or `.circleci` folder, or a `Dockerfile`, `docker-compose.yml` or `docker-compose.yaml`, exists. |
| `seo` | The framework detected in `package.json` is Next.js, Nuxt, Angular, React, Vue.js or Svelte. |

The health bar is a weighted checklist. Its score is the rounded share of the total weight of 10, and it only informs the closing advice: it never changes which packs are recommended.

**Health checklist**

| Check | Weight | Counted when |
| --- | --- | --- |
| Source code | 2 | a `src`, `lib` or `app` directory exists |
| Tests | 2 | a `tests`, `test`, `__tests__` or `spec` directory exists |
| Documentation | 1 | a `docs`, `doc` or `documentation` directory exists |
| CI/CD | 1 | a `.github`, `.gitlab-ci` or `.circleci` directory exists |
| Git | 1 | a `.git` directory or a `.gitignore` file exists |
| README | 1 | `README.md` or `readme.md` exists |
| License | 1 | `LICENSE` or `LICENSE.md` exists |
| Docker | 1 | `Dockerfile` or a docker-compose file exists |

Stack detection reads `package.json` first (framework, TypeScript, and the package manager from `pnpm-lock.yaml`, `yarn.lock` or `bun.lockb`, otherwise npm). Without a `package.json` it looks for `Cargo.toml` (Rust), `pyproject.toml` or `requirements.txt` (Python), `go.mod` (Go), `composer.json` (PHP), `Gemfile` (Ruby), `pom.xml` or `build.gradle` (Java).

<a id="new-project"></a>
### New project

In an empty folder it asks the project type, then a one-sentence description, and installs the packs that go with the type.

**Packs per project type**

| Project type | Packs installed |
| --- | --- |
| Web Application | `core`, `memory`, `dev-studio`, `seo` |
| API / Backend | `core`, `memory`, `dev-studio`, `shield` |
| CLI Tool | `core`, `memory` |
| Mobile App | `core`, `memory`, `dev-studio` |
| Library / Package | `core`, `memory`, `dev-studio` |
| Other | `core`, `memory` |

<a id="reads-writes"></a>
## What it reads and writes

- Reads: the top-level entries of the folder, `package.json`, `tsconfig.json`, the lockfiles and the other manifests listed above. It makes no network request and starts no other process.
- Writes: everything `install` writes for the chosen packs (it calls the installer with `--yes`), then `.agents/memory/context.md`.
- Instruction files: if `CLAUDE.md`, `GEMINI.md` or `AGENTS.md` already exists at the root, it passes `--tools none` and leaves every adapter alone. Otherwise it passes the tools whose marker folder it finds (for example `.claude`), or `none` when there is none.
- In a new project it passes no `--tools` option, so the installer auto-detects and, under `--yes`, writes no adapter when it finds no tool.

> **Warning · context.md is rewritten** autoconfig replaces `.agents/memory/context.md` with a generated file (stack, structure, health, key directories, installed packs, or the project brief for a new project). Anything you or an agent wrote there is overwritten. Run it once, at the start, not on a project whose context you have been curating.

<a id="exit-codes"></a>
## Exit codes

**Exit codes of autoconfig**

| Code | Meaning |
| --- | --- |
| 0 | Finished, or you declined or cancelled a prompt (nothing was installed in that case). |
| 1 | The installer it calls failed. autoconfig itself sets no code; the installer sets 1 when it refuses (for example a version conflict) or throws (the CLI then prints `BMAD+: <message>`). |

<a id="real-output"></a>
## What you see

**Existing Next.js project with a CI folder and no docs (simulated)** (Simulated)

```text
$ npx bmad-plus autoconfig --yes
BMAD+ Autoconfig
Existing project detected: invoice-app
Analysis complete
Project Analysis
  Stack:       Next.js + TypeScript + Node.js (npm)
  Structure:   src/  tests/  CI/CD  no docs
  Health:      ████████░░ 80%
Recommended Packs
  ✓ core         Essential multi-role agents (Atlas, Forge, Sentinel, Nexus)
  ✓ memory       Persistent brain for context continuity across sessions
  ✓ dev-studio   No docs/ found — Huldah (Tech Writer) will help document
  ✓ shield       CI/CD and/or Docker detected — GRC compliance agents recommended
  ✓ seo          Next.js web app detected — SEO audit agents recommended
# The installer then runs exactly as in the install page, without prompts.
Recommended Next Steps
  !  "Forge, document the project architecture and API"
  ·  "Forge, continue developing the current module"
  ·  "Zecher, consolidate session memory"
Autoconfig complete! 🚀
```

Illustrative transcript, not captured from a real run. Source: Composed from the message templates in tools/cli/commands/autoconfig.js; colours, emoji and box characters omitted

The health figure is the checklist above: this fictional project has sources, tests, CI, git, README and license (8 of 10), but no docs and no Docker. The next steps come from fixed rules: missing tests give a high-priority Sentinel step, missing docs and CI give Forge steps, a score under 60 percent adds a Sentinel review, source code adds “continue developing”, and a Zecher step comes last. At most five steps are printed, so a project that triggers all five other rules does not see the Zecher step. The 80 percent assumes git, a README and a license, which the Structure line does not list: with git but without README and license, the same line shows 60 percent.

<a id="errors"></a>
## Errors and what to do

**autoconfig messages**

| Message | Cause | What to do |
| --- | --- | --- |
| `Autoconfig install failed: <message>` | The installer threw an error; the same error is then printed by the CLI as `BMAD+: <message>` and the exit code is 1. | Read the message, or run `install` directly to see the same failure in context. |
| `BMAD+ v<old> is installed; this package is v<new>. Run bmad-plus update first ...` | The project holds another BMAD+ version. The installer refuses and sets exit code 1, yet autoconfig still prints its own closing lines. | Run `update`, then autoconfig again. Do not read “Installation complete” as success when the exit code is 1. |
| `Autoconfig cancelled.` | You answered no to the confirmation, or cancelled a wizard question. | Nothing was installed. Run it again when ready. |
| `autoconfig: Failed to list directory <message>` | The folder could not be read. The result is an empty list, so it is treated as a new project. | Check the path given to `--directory` and its permissions before answering the wizard. |

<a id="examples"></a>
## Examples

<a id="example-cli-autoconfig-existing-repo"></a>
### Set up an unfamiliar repository

You cloned a project you do not know and want BMAD+ to pick the packs.

**In your AI assistant**

```text
Run `npx bmad-plus autoconfig --yes` in this repository. Then tell me which packs it recommended and why, and which agent request it suggests first.
```

**What you should get** The assistant runs the command, which prints the analysis, one reason per recommended pack (`core` and `memory` always, the others from the rules above) and installs them. It reports the pack list with each printed reason and the first “Recommended Next Steps” line (the first rule that applies, for instance a Sentinel step when there are no tests). `.agents/memory/context.md` now holds the generated stack and health summary.

<a id="example-cli-autoconfig-new-idea"></a>
### Start from an empty folder

You have only an idea and an empty directory, and you can answer two questions in the terminal.

**In your AI assistant**

```text
In this empty folder run `npx bmad-plus autoconfig`. When it asks, choose “Web Application” and describe the project as: a booking page for a small physiotherapy practice.
```

**What you should get** It prints “Empty directory — starting new project wizard”, installs `core`, `memory`, `dev-studio` and `seo` (the Web Application set), writes `.agents/memory/context.md` with the type, your description and the status “New — not started”, and prints four first steps: ask Atlas to build the described project, ask Atlas for the PRD, ask Forge for the architecture, or say “autopilot”.

**See also**

- [install: choose packs and tools yourself](https://bmad-plus.rochetta.fr/docs/reference/cli-install/)
- [memory: read the project memory autoconfig seeds](https://bmad-plus.rochetta.fr/docs/reference/cli-memory/)
- [doctor: check the installation afterwards](https://bmad-plus.rochetta.fr/docs/reference/cli-doctor/)
- [Project layout](https://bmad-plus.rochetta.fr/docs/reference/project-layout/)

[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)