Installation Guide

Complete installation guide for BMad Method including prerequisites, installation methods, verification, and troubleshooting

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

1. 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
   
2. Terminal access

   You need command-line access to run the installer.

   • macOS/Linux: Built-in Terminal
   • Windows: PowerShell, Command Prompt, or Windows Terminal
3. 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.

1. Navigate to your project

   cd /path/to/your/project
   
2. Run the installer

   npx bmad-method install
   

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

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

5. 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…
6. 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.

Basic Non-Interactive

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.

1. Check installation status

   npx bmad-method status
   

   This shows:

   • Installed modules
   • Configured IDEs
   • Agent count
   • Workflow count
2. Verify directory structure

   ls -la _bmad
   

   You should see:

   • core/ directory
   • Module directories (e.g., bmm/)
   • manifest.yaml file
3. Check IDE integration

   Open your AI IDE and verify slash commands are available:

   /bmad-help
   

   If this works, your installation is successful!

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

Error: BMad Method requires Node.js v20 or higher

Solution:

# Check version
node --version

# Update Node.js
nvm install 20
nvm use 20

Permission Errors

Error: EACCES: permission denied

Solution:

# 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

Stale Cache

Error: Getting an old version

Solution:

# Clear npm cache
npm cache clean --force

# Use specific version
npx bmad-method@6.0.4 install

Network Issues

Error: ETIMEDOUT or network errors

Solution:

# 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

1. Verify IDE integration

   Check that your IDE’s command directory exists:

   # Claude Code
   ls -la .claude/commands/bmad
   
   # Cursor
   ls -la .cursor/commands/bmad
   
2. Restart your IDE

   Close and reopen your AI IDE to reload command files.

3. Reinstall IDE integration

   npx bmad-method install --action update
   # Select your IDE again
   
4. Check IDE compatibility

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

Agents Not Responding

Check Agent Files

ls -la _bmad/bmm/agents/

Verify agent files exist (.md format).

Recompile Agents

npx bmad-method install --action compile-agents

Check Configuration

cat _bmad/core/config.yaml

Verify configuration is valid YAML.

Installation Hangs

If installation hangs during prompts, try:

1. Use non-interactive mode with --yes flag
2. Check terminal compatibility (use native terminal, not IDE terminal)
3. 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!