Installation Guide

This comprehensive guide covers everything you need to install and configure BMad Method for your project.

Prerequisites

Before installing BMad Method, ensure you have:

Required

Node.js v20 or higher

BMad Method requires Node.js version 20.0.0 or higher.Check your version:

node --version

Install or update Node.js:

Download from nodejs.org
Use a version manager like nvm (recommended)

# Using nvm
nvm install 20
nvm use 20

Terminal access

You need command-line access to run the installer.

macOS/Linux: Built-in Terminal
Windows: PowerShell, Command Prompt, or Windows Terminal

AI IDE (recommended)

While not strictly required, BMad Method is designed to work with AI IDEs:

Claude Code (recommended)
Cursor
Windsurf
GitHub Copilot
Codex
Rovo Dev
Kilo

BMad can work with any IDE, but AI IDEs provide the best experience through slash commands and agent integration.

Optional

Git — For version control and tracking changes
Project directory — BMad works with new or existing projects

Installation Methods

BMad Method supports multiple installation approaches.

Interactive Installation (Recommended)

The interactive installer guides you through configuration with prompts.

Navigate to your project

cd /path/to/your/project

Run the installer

npx bmad-method install

Using npx ensures you always get the latest version without global installation.

Follow the prompts

The installer will ask you to configure:

Core Configuration

User name: What agents should call you
Communication language: Language for agent conversations (default: English)
Document output language: Language for generated documents (default: English)
Output folder: Where to save artifacts (default: _bmad-output)
Subagent support: Whether your LLM/tool supports subagents
Agent team support: Whether your LLM/tool supports agent teams

BMad Method Configuration

Project name: Your project’s name
Experience level: Beginner, Intermediate, or Expert
Planning artifacts: Where to store Phase 1-3 artifacts
Implementation artifacts: Where to store Phase 4 artifacts
Project knowledge: Where to store long-term documentation

Select modules

Choose which modules to install:

BMad Method (BMM)

Core framework with 34+ workflows for full agile lifecycle Recommended for all projects

BMad Builder (BMB)

Create custom agents, workflows, and modules For advanced users and extenders

Test Architect (TEA)

Risk-based test strategy and automation For QA-focused projects

Game Dev Studio (BMGD)

Unity, Unreal, and Godot workflows For game development projects

Creative Intelligence Suite (CIS)

Innovation, brainstorming, design thinking For creative and innovation work

You can install additional modules later by running the installer again.

Select IDE(s)

Choose your AI IDE(s). The installer supports multiple selections.The installer will generate appropriate configuration files for each selected IDE:

Claude Code: .claude/commands/
Cursor: .cursor/commands/
GitHub Copilot: .github/copilot/
Windsurf: .windsurf/
And more…

Wait for completion

The installer will:

Create directory structure
Install selected modules
Compile agent files
Generate workflow commands
Configure IDE integrations

Installation typically takes 30-60 seconds.

Non-Interactive Installation

For CI/CD pipelines, automation, or scripting.

npx bmad-method install \
  --directory /path/to/project \
  --modules bmm \
  --tools claude-code \
  --yes

Non-Interactive Flags

Flag	Description	Example
`--directory <path>`	Installation directory	`--directory /path/to/project`
`--modules <modules>`	Comma-separated module IDs	`--modules bmm,tea,bmb`
`--tools <tools>`	Comma-separated IDE IDs	`--tools claude-code,cursor`
`--user-name <name>`	Name for agents to use	`--user-name "Alex"`
`--communication-language <lang>`	Agent communication language	`--communication-language Spanish`
`--document-output-language <lang>`	Document output language	`--document-output-language English`
`--output-folder <path>`	Output folder path	`--output-folder _bmad-output`
`-y, --yes`	Accept all defaults	`--yes`
`--action <type>`	Action type	`--action update`
`--custom-content <paths>`	Custom modules/agents	`--custom-content ./custom`
`-d, --debug`	Enable debug output	`--debug`

Use --tools none in CI/CD environments where IDE integration isn’t needed.

Custom Module Installation

Install custom or third-party modules:

npx bmad-method install \
  --custom-content /path/to/custom/module \
  --custom-content /path/to/another/module

Installation Directory Structure

After successful installation, you’ll see:

your-project/
├── _bmad/                          # BMad installation directory
│   ├── core/                       # Core module
│   │   ├── config.yaml            # Core configuration
│   │   ├── agents/                # Core agents
│   │   └── workflows/             # Core workflows
│   ├── bmm/                       # BMad Method module
│   │   ├── module.yaml            # Module configuration
│   │   ├── agents/                # BMM agents
│   │   │   ├── pm.md             # Product Manager agent
│   │   │   ├── architect.md      # Architect agent
│   │   │   ├── dev.md            # Developer agent
│   │   │   ├── ux-designer.md    # UX Designer agent
│   │   │   └── ...
│   │   └── workflows/             # BMM workflows
│   │       ├── 1-analysis/       # Research workflows
│   │       ├── 2-plan-workflows/ # Planning workflows
│   │       ├── 3-solutioning/    # Architecture workflows
│   │       └── 4-implementation/ # Sprint workflows
│   ├── manifest.yaml              # Installation manifest
│   └── [other modules]/           # Additional modules
├── _bmad-output/                  # Default output directory
│   ├── planning-artifacts/        # Phase 1-3 artifacts
│   └── implementation-artifacts/  # Phase 4 artifacts
├── .claude/                       # Claude Code integration (if selected)
│   └── commands/
│       └── bmad/                 # BMad slash commands
├── .cursor/                       # Cursor integration (if selected)
│   └── commands/
│       └── bmad/
└── docs/                          # Project knowledge (configurable)

The _bmad directory should be committed to version control so your team shares the same configuration.

Verification

Verify your installation is working correctly.

Check installation status

npx bmad-method status

This shows:

Installed modules
Configured IDEs
Agent count
Workflow count

Verify directory structure

ls -la _bmad

You should see:

core/ directory
Module directories (e.g., bmm/)
manifest.yaml file

Check IDE integration

Open your AI IDE and verify slash commands are available:

/bmad-help

If this works, your installation is successful!

Test an agent

Try invoking an agent:

/pm

You should see the Product Manager agent menu.

Updating BMad Method

Keep your installation up to date.

Check for Updates

The CLI automatically checks for updates when you run it:

npx bmad-method install

If an update is available, you’ll see a notification.

Quick Update

Update modules while preserving your configuration:

npx bmad-method install --action quick-update

This:

Updates all installed modules to the latest version
Preserves your configuration settings
Recompiles agents
Updates workflow files

Full Update

For major version updates or configuration changes:

npx bmad-method install --action update

This allows you to:

Update configuration
Add or remove modules
Change IDE integrations

Recompile Agents Only

If you’ve customized agents and want to recompile:

npx bmad-method install --action compile-agents

Always clear your npm cache before updating to avoid stale versions:

npm cache clean --force
npx bmad-method@latest install

Uninstalling

Remove BMad Method from your project.

Interactive Uninstall

npx bmad-method uninstall

Choose what to remove:

Specific modules
IDE integrations
Complete uninstall

Complete Uninstall

Manually remove all BMad files:

# Remove BMad directory
rm -rf _bmad

# Remove output directory (if desired)
rm -rf _bmad-output

# Remove IDE integrations
rm -rf .claude/commands/bmad
rm -rf .cursor/commands/bmad
# etc.

Troubleshooting

Common issues and solutions.

Installation Fails

Node Version
Permission Errors
Stale Cache
Network Issues

Error: BMad Method requires Node.js v20 or higherSolution:

# Check version
node --version

# Update Node.js
nvm install 20
nvm use 20

Error: EACCES: permission deniedSolution:

# Don't use sudo with npx
# Instead, fix npm permissions:
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
export PATH=~/.npm-global/bin:$PATH

Error: Getting an old versionSolution:

# Clear npm cache
npm cache clean --force

# Use specific version
npx [email protected] install

Error: ETIMEDOUT or network errorsSolution:

# Check npm registry
npm config get registry

# Use default registry
npm config set registry https://registry.npmjs.org/

# Retry with longer timeout
npm config set fetch-timeout 60000

Slash Commands Not Working

Verify IDE integration

Check that your IDE’s command directory exists:

# Claude Code
ls -la .claude/commands/bmad

# Cursor
ls -la .cursor/commands/bmad

Restart your IDE

Close and reopen your AI IDE to reload command files.

Reinstall IDE integration

npx bmad-method install --action update
# Select your IDE again

Check IDE compatibility

Ensure your IDE version supports custom commands. Update to the latest version.

Agents Not Responding

Check Agent Files
Recompile Agents
Check Configuration

ls -la _bmad/bmm/agents/

Verify agent files exist (.md format).

npx bmad-method install --action compile-agents

cat _bmad/core/config.yaml

Verify configuration is valid YAML.

Installation Hangs

If installation hangs during prompts, try:

Use non-interactive mode with --yes flag
Check terminal compatibility (use native terminal, not IDE terminal)
On Windows, try PowerShell instead of Command Prompt

Module Not Found

Error: Module 'bmm' not found Solution:

# Reinstall the module
npx bmad-method install
# Select BMM module when prompted

Custom Module Installation Fails

Error: Issues with --custom-content Solution:

Verify the path exists and is accessible
Check module.yaml syntax in custom module
Use absolute paths instead of relative paths

Advanced Configuration

Environment Variables

Set environment variables for advanced control:

# Enable debug mode
export BMAD_DEBUG_MANIFEST=true

# Custom installation directory
export BMAD_INSTALL_DIR=./custom-bmad

Multiple Installations

You can have different BMad configurations for different projects:

# Project A - Full setup
cd ~/projects/project-a
npx bmad-method install --modules bmm,tea,bmb

# Project B - Minimal setup
cd ~/projects/project-b
npx bmad-method install --modules bmm --yes

Workspace Configuration

For monorepos, install BMad at the workspace root:

monorepo/
├── _bmad/              # Shared BMad installation
├── packages/
│   ├── app-1/
│   └── app-2/
└── package.json

Getting Help

Discord Community

Get help from the community and BMad team

GitHub Issues

Report bugs and request features

Documentation

Browse the complete documentation site

YouTube

Watch tutorials and master classes

Still having issues? Run /bmad-help troubleshooting in your IDE for context-specific help.

What’s Next?

Now that BMad Method is installed:

Try your first workflow — Run /create-prd to create a product requirements document
Explore agents — Invoke /pm, /architect, or /dev to meet the team
Learn workflows — Check the workflow guide to understand the full development lifecycle
Customize — Edit _bmad/core/config.yaml to adjust agent behavior

Remember: /bmad-help is your intelligent guide. Use it anytime you’re unsure what to do next!

Get Started

Tutorials

Core Concepts

How-To Guides

Workflows

Advanced Topics

​Installation Guide

​Prerequisites

​Required

​Optional

​Installation Methods

​Interactive Installation (Recommended)

​Core Configuration

​BMad Method Configuration

BMad Method (BMM)

BMad Builder (BMB)

Test Architect (TEA)

Game Dev Studio (BMGD)

Creative Intelligence Suite (CIS)

​Non-Interactive Installation

​Non-Interactive Flags

​Custom Module Installation

​Installation Directory Structure

​Verification

​Updating BMad Method

​Check for Updates

​Quick Update

​Full Update

​Recompile Agents Only

​Uninstalling

​Interactive Uninstall

​Complete Uninstall

​Troubleshooting

​Installation Fails

​Slash Commands Not Working

​Agents Not Responding

​Installation Hangs

​Module Not Found

​Custom Module Installation Fails

​Advanced Configuration

​Environment Variables

​Multiple Installations

​Workspace Configuration

​Getting Help

Discord Community

GitHub Issues

Documentation

YouTube

​What’s Next?

Build docs developers (and LLMs) love

Installation Guide

Prerequisites

Required

Optional

Installation Methods

Interactive Installation (Recommended)

Core Configuration

BMad Method Configuration

Non-Interactive Installation

Non-Interactive Flags

Custom Module Installation

Installation Directory Structure

Verification

Updating BMad Method

Check for Updates

Quick Update

Full Update

Recompile Agents Only

Uninstalling

Interactive Uninstall

Complete Uninstall

Troubleshooting

Installation Fails

Slash Commands Not Working

Agents Not Responding

Installation Hangs

Module Not Found

Custom Module Installation Fails

Advanced Configuration

Environment Variables

Multiple Installations

Workspace Configuration

Getting Help

What’s Next?