scan answers the question “which projects do I have, and which of them already use BMAD+?”. It walks a directory, recognises project roots, guesses the stack, classifies each project as active, paused or archived, and records one small card per project in the global brain, the personal memory folder shared by all your projects (~/.bmad-plus/brain). It is for people who keep many repositories and want one agent, usually Zecher, to know them all.
A folder is a project root when it contains one of these files, tested in this order: package.json, Cargo.toml, pyproject.toml, requirements.txt, go.mod, composer.json, Gemfile, pom.xml, build.gradle. The scan does not descend into a project once it has found its root.
A folder below the starting point that has a .git directory but none of those files is also a project, with the stack “Unknown”. The starting directory itself only counts through the marker files.
The stack comes from the marker: Rust, Python, Go, PHP, Ruby, Java or Java/Kotlin, and for package.json one of Next.js, Nuxt, React, Vue.js, Svelte, Express, Fastify, Electron, Tauri (checked in that order against dependencies and devDependencies), otherwise Node.js.
These folders are skipped: node_modules, .git, vendor, __pycache__, dist, build, .next, .nuxt, .svelte-kit, target, .venv, venv, .cache, .output, coverage, .turbo, .angular, and the Windows system folders $RECYCLE.BIN, System Volume Information, Windows, Program Files, Program Files (x86), ProgramData, AppData, Recovery, PerfLogs. Every other folder whose name starts with a dot is skipped too. Folders it cannot read are skipped silently.
Activity is the modification time of the project folder itself. That time changes when entries are added or removed directly inside it, not when you edit a file deeper down, so a busy project can still read as “paused”. Adjust --active-days and --paused-days if the labels do not match how you work.
The BMAD+ column is a check mark when the project has an .agents or _bmad folder.
One card per indexed project: path, name, hash, stack, status, bmad_installed, has_git, last_scanned (a date). The 8-character hash comes from the project path, so scanning the same project twice updates its card instead of adding a second one.
.bmad-plus/brain/projects-index.md
A Markdown table of every card in the projects/ folder (not only this run), rewritten after each scan that indexes something.
The scanned projects themselves are only read, never modified. The brain location is fixed at ~/.bmad-plus/brain: scan does not follow the BMAD_PLUS_BRAIN variable or a portfolio _brain folder that install may have linked. No network request is made.
Every normal ending: indexed, nothing found, cancelled, and also “Directory not found”.
1
An unexpected error escaped (the CLI prints BMAD+: <message>). scan sets no other code.
Note· Do not rely on the exit code in scripts
A wrong path still ends with code 0 after printing the error. In a script, check the directory yourself before calling scan, and pass --yes so nothing waits for an answer.
Scanning a work folder with --yes (simulated)Simulated
$ npx bmad-plus scan ~/work --depth 3 --yesBMAD+ Project ScannerFound 3 project(s) Legend: ● active modified < 30 days ago (2 found) ◐ paused modified 30–180 days ago (1 found) ○ archived modified > 180 days ago (0 found) # Status BMAD+ Stack Name Path ────────────────────────────────────────────────────────────────────────────────────────── 1 ● active ✓ Next.js invoice-app /home/me/work/invoice-app 2 ● active · Python etl-jobs /home/me/work/etl-jobs 3 ◐ paused · Unknown notes-site /home/me/work/notes-site✅ 3 project(s) indexed in /home/me/.bmad-plus/brain/projects📋 Project index updated: /home/me/.bmad-plus/brain/projects-index.mdScan complete! 🧠
npx bmad-plus scan ~/work --depth 3 --yes
Illustrative transcript, not captured from a real run. Source: Composed from the message templates in tools/cli/commands/scan.js; colours, emoji and the framing of the prompt library omitted. Names and paths are invented.
Read the table left to right: the number, the activity class, whether BMAD+ is installed, the detected stack, the project name (from package.json when there is one, otherwise the folder name, cut to 20 characters) and the path (cut to its last 37 characters when longer than 40). Without --yes, scan asks instead: index all, pick projects from a list, or skip.
Index a work folder and find the projects without BMAD+#
You keep about a dozen repositories under one folder and want a list of the active ones that BMAD+ has not touched.
In your AI assistant
Run `npx bmad-plus scan ~/work --yes`. Then read ~/.bmad-plus/brain/projects-index.md and list the projects whose status is active and whose BMAD+ column is empty.
What you should get The command prints the legend and table, writes one <hash>.yaml card per project and rewrites projects-index.md. The assistant reads that table (columns Status, Name, Stack, BMAD+, Path; a check mark means installed, a dot means not) and returns the rows that are active with a dot. The index covers every card in the brain, so it may also list projects from earlier scans or installs.
Requires the memory pack. This is the agent’s own scan workflow, which asks you about each project, not the command above.
In your AI assistant
Zecher, scan projects in ~/work.
What you should get Zecher walks the folder, shows a table (project, stack, status, BMAD+, last modified) and asks for each project: confirm, edit, skip, or install BMAD+ there. Only the confirmed projects are written to ~/.bmad-plus/brain/projects/<hash>.yaml, the index is updated, and Zecher reports how many were indexed, new and updated.