Installing BMAD and starting work (any machine)

This page takes you from a clean machine to a working BMAD install you can run in your IDE. It is exact: every command, flag, and prerequisite is drawn from the v6.10 installer and docs. If you only read one page to get running, read this one, then jump to the anatomy page to learn what the installer wrote and what to commit.

On this page

• Prerequisites
• The one command
• Where your skills landed (per IDE)
• Non-interactive and CI installs
• Adding, updating, and pinning later
• Upgrading from v4
• Planning on a flat rate: web bundles
• Hands-on: install BMAD and run your first skill in 10 minutes
• Under Claude Code: where BMAD lands and how it is discovered

Prerequisites

BMAD is an npm package (bmad-method) that generates skill files into your project. It needs three things on the machine, whatever the OS:

Two version notes worth knowing before you hit them:

• The README badges say Python 3.10+, but the customization resolver needs 3.11+ (tomllib landed in 3.11). On macOS without Homebrew and on Ubuntu 22.04, python3 often defaults to 3.10, so install 3.11+ separately or rely on uv, which provisions its own Python.
• Node must be 20.12 or newer or the installer refuses to run.

Per-OS setup, briefly

The installer itself is OS-agnostic; the only per-OS work is getting Node, uv, and Python present.

• macOS: brew install node uv python@3.12 (or use the official Node and astral.sh/uv installers). Apple Silicon and Intel are both fine.
• Linux: install Node 20.12+ from NodeSource or your distro, curl -LsSf https://astral.sh/uv/install.sh | sh for uv, and Python 3.11+ from your package manager (Ubuntu 22.04 users: add deadsnakes or use uv).
• Windows: install Node from nodejs.org, uv via the PowerShell installer, and run inside WSL2 or a normal PowerShell/terminal that your AI tool can reach. Everything below works unchanged under WSL2.

The one command

From inside your project directory:

npx bmad-method install

That single command handles first installs, upgrades, channel switching, and scripted CI runs. On a fresh project it runs an interactive wizard; on a project that already has a _bmad/ folder it offers to update instead.

The interactive wizard asks five things

1. Install directory (defaults to the current directory).
2. Which modules to install: checkboxes for core, bmm, bmb, cis, gds, tea. (core and bmm are the method itself; the rest are add-ons, covered on the map page.)
3. "Ready to install (all stable)?" Yes takes the latest released tag of every external module.
4. Which AI tools / IDEs to integrate with (Claude Code, Cursor, and others).
5. Per-module config: your name, language, and output folder.

When it finishes you have two new folders, _bmad/ (the method) and _bmad-output/ (where artifacts land), and a set of bmad-* skills registered for your IDE. Start with:

bmad-help

which inspects the project and tells you the next step. From a blank project that is usually "create a PRD" or, for a small change, "run quick-dev."

Where your skills landed (per IDE)

The installer writes one skill directory per agent, workflow, task, and tool into an IDE-specific folder. The directory name is the skill name.

Some platforms require you to enable skills in settings before they appear, and a few need an IDE reload. The canonical list of what you have is always the directories themselves:

find .claude/skills -maxdepth 1 -type d -name 'bmad-*' | sort

Non-interactive and CI installs

For reproducible, scripted installs, pass flags. Two are effectively required for a fresh --yes run: --modules (the exact set to install, not a delta, so list everything you want) and --tools (which IDE to wire up).

# Latest stable, everything wired for Claude Code
npx bmad-method install --yes --modules bmm,bmb,cis --tools claude-code

The flags that matter most:

Precedence when they conflict: --pin beats --next= beats --channel/--all-* beats the registry default (stable).

Two channels are in play, and they are independent. The external-module channel (stable, next, or a pinned tag) is per module. The installer binary itself has @latest (npx bmad-method install) and @next (npx bmad-method@next install, a prerelease published on every push to main). Because core and bmm ship inside the installer binary, they have no channel: the installer version determines them, and --pin bmm=... is silently ignored with a warning.

An enterprise-grade, fully reproducible install pins each external module:

npx bmad-method install --yes \
  --modules bmm,bmb,cis \
  --pin bmb=v1.7.0 --pin cis=v0.2.0 \
  --tools claude-code

Heads-up for orgs and CI: resolving each external module's "stable" tag makes one anonymous GitHub API call, and anonymous calls are capped at 60 per hour per IP. Shared NAT, VPNs, and CI pools exhaust that fast. Set GITHUB_TOKEN=<any public-repo-read PAT> to raise the limit to 5000/hour; no scopes are required.

Adding, updating, and pinning later

Running the installer again on an existing project gives you two paths:

• Quick Update reuses your recorded settings, refreshes files, applies patch and minor upgrades, and refuses majors. Fast and non-interactive.
• Modify Install is the full wizard again: add or remove modules, reconfigure, review channels.

To add a module to an existing install without re-selecting your IDE (update reuses the configured tools):

npx bmad-method install --yes --action update --modules bmm,bmb,gds

Upgrade defaults are patch = yes, minor = yes, major = no. Under --yes, patches and minors auto-apply and majors stay frozen; to accept a major non-interactively, pin the new tag: --pin <code>=<new-tag>.

Upgrading from v4

If a project has a legacy .bmad-method folder, npx bmad-method install detects it and offers to back it up and remove it. Then:

1. Let the installer remove .bmad-method (or exit and clean manually; custom-named folders must be removed by hand).
2. Delete legacy v4 IDE commands. For Claude Code, remove the nested bmad folders under .claude/commands/; v6 installs to .claude/skills/.
3. Move planning docs into _bmad-output/planning-artifacts/ with descriptive names (include PRD, brief, architecture, or ux-design in the filename so the auto-scanner finds them).
4. For in-progress dev, drop your epics.md (or epics/epic*.md) into planning-artifacts, run bmad-sprint-planning, and tell the agent which stories are already done.

There is no supported v4/v6 coexistence; the compatibility shims that keep old skill names resolving are the intended bridge.

Planning on a flat rate: web bundles

Long planning conversations (brainstorm, brief, PRD, UX, research) can run on a flat-rate chat subscription instead of metered IDE tokens, then come back to the IDE for implementation. BMAD packages these as Gemini Gems and ChatGPT Custom GPTs. The only supported source is bmadcode.com/web-bundles: pick a bundle, download the ZIP, create a Gem or Custom GPT, upload the knowledge files, and paste the instructions block. Gemini Gems need Gemini Advanced; Custom GPTs need a paid ChatGPT plan; the research bundles need Deep Research enabled. Details are on the team page.

Hands-on: install BMAD and run your first skill in 10 minutes

Empty repo to a working skill. Every command is exact; anything the tool prints back is labeled illustrative.

1. Check prerequisites. Confirm the three from the table above:

node --version
python3 --version
uv --version

Illustrative (run it in your own repo; not machine-verified here).

v20.12.2
Python 3.12.4
uv 0.5.11

If node is below 20.12 the installer aborts; if python3 is below 3.11, let uv provide Python rather than fighting the system one.

2. Run the installer from inside a git repo:

cd my-project
npx bmad-method install

The wizard prompts through the five questions from the section above. Pick Claude Code as the IDE and core + bmm as the modules for a first run:

? Install directory  .
? Modules  (*) core  (*) bmm  ( ) bmb  ( ) cis  ( ) gds  ( ) tea
? Ready to install (all stable)?  Yes
? AI tools / IDEs  (*) Claude Code
? Your name  Sam

Illustrative (run it in your own repo; not machine-verified here).

3. See what landed. Two folders plus the Claude Code skills tree:

ls -R _bmad | head
ls .claude/skills

Illustrative (run it in your own repo; not machine-verified here).

_bmad:
core  bmm  _cfg

_bmad/core:
agents  workflows  tasks

.claude/skills:
bmad-help  bmad-brainstorming  bmad-create-prd  bmad-quick-dev  bmad-sprint-planning

4. Confirm discovery. In Claude Code, list what registered:

/skills

Illustrative (run it in your own repo; not machine-verified here).

bmad-help            Inspect the project and suggest the next step
bmad-brainstorming   Facilitated idea generation for a new feature or product
bmad-create-prd      Draft a product requirements document

No registration step: the host reads each SKILL.md frontmatter directly (see the next section).

5. Run your first skill.

/bmad-brainstorming

Illustrative (run it in your own repo; not machine-verified here).

> What problem or opportunity are we brainstorming today?
you: a CLI that lints commit messages
> Good. Let us diverge first. Give me three user types who would care...

That is the loop: invoke a bmad-* skill, answer its questions, get a drafted artifact under _bmad-output/.

6. Commit the right files. Check in the shared config and skills; keep personal settings out:

git add _bmad .claude/skills .claude/settings.json .mcp.json
echo '.claude/settings.local.json' >> .gitignore
echo '_bmad-output/' >> .gitignore

The exact commit-versus-ignore list, and why _bmad-output/ is generated rather than committed, is on page 3.

Under Claude Code: where BMAD lands and how it is discovered

This page is about install and what to commit. On Claude Code the mapping is direct: a --tools claude-code run drops one directory per agent, workflow, and task under .claude/skills/<name>/SKILL.md, and the host discovers them with no registration step.

Discovery reads the description line in each SKILL.md frontmatter. Progressive disclosure keeps only the name and description in context (about 50 tokens each) until a skill is invoked, so even a large bmad-* install stays cheap; the full body loads on first use. /skills lists what you have and toggles each one on, name-only, or off.

Where a skill lives sets its scope and its commit story:

Precedence when a name collides: enterprise-managed > personal (~/.claude) > project (.claude) > plugin.

The chapter's commit rule (share the config, gitignore the personal bits) maps onto Claude Code's settings split. .claude/settings.json is committed and team-shared; .claude/settings.local.json is gitignored and personal. Project MCP servers, if BMAD wires any, go in a committed .mcp.json. So a checked-in .claude/skills/ plus .claude/settings.json and .mcp.json reproduce the install for a teammate on clone.

BMAD can also arrive as a plugin bundle installed via /plugin from a marketplace. Then its skills namespace as /bmad:<skill> and live inside the plugin, not in your .claude/, which changes nothing about how discovery or progressive disclosure work.

With BMAD installed and running, the next page opens the box: exactly what the installer wrote to disk, how its configuration layers resolve, and which files belong in your repository's main branch. 👉