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.
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.
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.
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).
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.
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>).
Existing Next.js project with a CI folder and no docs (simulated)Simulated
$ npx bmad-plus autoconfig --yesBMAD+ AutoconfigExisting project detected: invoice-appAnalysis completeProject 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! 🚀
npx bmad-plus autoconfig --yes
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.
You cloned a project you do not know and want BMAD+ to pick the packs.
In your AI assistant
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.
You have only an idea and an empty directory, and you can answer two questions in the terminal.
In your AI assistant
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”.