# scan

> Walk a directory tree, find your projects, detect their stack and activity, and index them in the global brain so BMAD+ knows your whole portfolio.

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

`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 id="synopsis"></a>
## Synopsis

**In your project terminal**

```sh
npx bmad-plus scan [path] [-d <path>] [--depth <n>] [--active-days <n>] [--paused-days <n>] [-y] [-l <code>]
```

**Options of scan**

| Flag | Argument | Default | What it does |
| --- | --- | --- | --- |
| `[path]` | path | current directory | Directory to scan. When both `[path]` and `-d` are given, `[path]` wins. |
| `-d, --directory <path>` | path | current directory | Same as `[path]`, as an option. |
| `--depth <n>` | integer > 0 | 4 | How many levels below the scanned directory to search. |
| `--active-days <n>` | integer > 0 | 30 | A project modified less than this many days ago is “active”. |
| `--paused-days <n>` | integer > 0 | 180 | Modified less than this many days ago (but not active) is “paused”; older is “archived”. |
| `-y, --yes` | none | off | Index every project found without asking. |
| `-l, --lang <code>` | en, fr, es, de, pt-br, ru, zh, he, ja, it | en | Accepted for consistency with the other commands; scan prints in English. |

<a id="how-it-scans"></a>
## How it recognises projects

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

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

**Files scan writes**

| Path (under your home folder) | Content |
| --- | --- |
| `.bmad-plus/brain/projects/<hash>.yaml` | 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.

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

**Exit codes of scan**

| Code | Meaning |
| --- | --- |
| 0 | 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.

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

**Scanning a work folder with --yes (simulated)** (Simulated)

```text
$ npx bmad-plus scan ~/work --depth 3 --yes
BMAD+ Project Scanner
Found 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.md
Scan complete! 🧠
```

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.

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

**scan messages**

| Message | Cause | What to do |
| --- | --- | --- |
| `Directory not found: <path>` then `Scan failed.` | The directory does not exist. Exit code stays 0. | Fix the path. |
| `Invalid --depth "<v>", defaulting to 4` (same for `--active-days`, default 30, and `--paused-days`, default 180) | The value is not a positive integer; the default is used and the scan goes on. | Pass a whole number above zero. |
| `No projects found.` then `Try scanning a different directory or increasing --depth` | No marker file or `.git` folder within the depth, or everything was in a skipped folder. | Scan the parent folder, or raise `--depth`. |
| `Scan cancelled.` | You chose “Skip” or cancelled a prompt. Nothing was written. | Run again and choose “Index all” or select projects. |

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

<a id="example-cli-scan-index-portfolio"></a>
### 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**

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

<a id="example-cli-scan-zecher"></a>
### Let Zecher scan with your approval per project

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**

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

**See also**

- [memory: read the brain scan fills](https://bmad-plus.rochetta.fr/docs/reference/cli-memory/)
- [install: add BMAD+ to a project scan found](https://bmad-plus.rochetta.fr/docs/reference/cli-install/)
- [autoconfig: bootstrap one project](https://bmad-plus.rochetta.fr/docs/reference/cli-autoconfig/)
- [CLI overview](https://bmad-plus.rochetta.fr/docs/reference/cli-overview/)

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