> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/bmad-code-org/BMAD-METHOD/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

<Steps>
  <Step title="Node.js v20 or higher">
    BMad Method requires Node.js version 20.0.0 or higher.

    **Check your version:**

    ```bash theme={null}
    node --version
    ```

    **Install or update Node.js:**

    * Download from [nodejs.org](https://nodejs.org)
    * Use a version manager like [nvm](https://github.com/nvm-sh/nvm) (recommended)

    ```bash theme={null}
    # Using nvm
    nvm install 20
    nvm use 20
    ```
  </Step>

  <Step title="Terminal access">
    You need command-line access to run the installer.

    * **macOS/Linux:** Built-in Terminal
    * **Windows:** PowerShell, Command Prompt, or Windows Terminal
  </Step>

  <Step title="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**

    <Note>
      BMad can work with any IDE, but AI IDEs provide the best experience through slash commands and agent integration.
    </Note>
  </Step>
</Steps>

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

<Steps>
  <Step title="Navigate to your project">
    ```bash theme={null}
    cd /path/to/your/project
    ```
  </Step>

  <Step title="Run the installer">
    ```bash theme={null}
    npx bmad-method install
    ```

    <Tip>
      Using `npx` ensures you always get the latest version without global installation.
    </Tip>
  </Step>

  <Step title="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
  </Step>

  <Step title="Select modules">
    Choose which modules to install:

    <CardGroup cols={2}>
      <Card title="BMad Method (BMM)" icon="diagram-project">
        Core framework with 34+ workflows for full agile lifecycle
        **Recommended for all projects**
      </Card>

      <Card title="BMad Builder (BMB)" icon="wrench">
        Create custom agents, workflows, and modules
        **For advanced users and extenders**
      </Card>

      <Card title="Test Architect (TEA)" icon="vial">
        Risk-based test strategy and automation
        **For QA-focused projects**
      </Card>

      <Card title="Game Dev Studio (BMGD)" icon="gamepad">
        Unity, Unreal, and Godot workflows
        **For game development projects**
      </Card>

      <Card title="Creative Intelligence Suite (CIS)" icon="lightbulb">
        Innovation, brainstorming, design thinking
        **For creative and innovation work**
      </Card>
    </CardGroup>

    <Note>
      You can install additional modules later by running the installer again.
    </Note>
  </Step>

  <Step title="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...
  </Step>

  <Step title="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.
  </Step>
</Steps>

### Non-Interactive Installation

For CI/CD pipelines, automation, or scripting.

<CodeGroup>
  ```bash Basic Non-Interactive theme={null}
  npx bmad-method install \
    --directory /path/to/project \
    --modules bmm \
    --tools claude-code \
    --yes
  ```

  ```bash Complete Configuration theme={null}
  npx bmad-method install \
    --directory /path/to/project \
    --modules bmm,tea \
    --tools claude-code,cursor \
    --user-name "Engineering Team" \
    --communication-language English \
    --document-output-language English \
    --output-folder _bmad-output \
    --yes
  ```

  ```bash CI/CD Example theme={null}
  # .github/workflows/setup-bmad.yml
  - name: Install BMad Method
    run: |
      npx bmad-method install \
        --directory ${{ github.workspace }} \
        --modules bmm \
        --tools none \
        --yes
  ```
</CodeGroup>

#### 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`                            |

<Tip>
  Use `--tools none` in CI/CD environments where IDE integration isn't needed.
</Tip>

### Custom Module Installation

Install custom or third-party modules:

```bash theme={null}
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:

```bash theme={null}
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)
```

<Note>
  The `_bmad` directory should be committed to version control so your team shares the same configuration.
</Note>

## Verification

Verify your installation is working correctly.

<Steps>
  <Step title="Check installation status">
    ```bash theme={null}
    npx bmad-method status
    ```

    This shows:

    * Installed modules
    * Configured IDEs
    * Agent count
    * Workflow count
  </Step>

  <Step title="Verify directory structure">
    ```bash theme={null}
    ls -la _bmad
    ```

    You should see:

    * `core/` directory
    * Module directories (e.g., `bmm/`)
    * `manifest.yaml` file
  </Step>

  <Step title="Check IDE integration">
    Open your AI IDE and verify slash commands are available:

    ```bash theme={null}
    /bmad-help
    ```

    If this works, your installation is successful!
  </Step>

  <Step title="Test an agent">
    Try invoking an agent:

    ```bash theme={null}
    /pm
    ```

    You should see the Product Manager agent menu.
  </Step>
</Steps>

## Updating BMad Method

Keep your installation up to date.

### Check for Updates

The CLI automatically checks for updates when you run it:

```bash theme={null}
npx bmad-method install
```

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

### Quick Update

Update modules while preserving your configuration:

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
npx bmad-method install --action compile-agents
```

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

  ```bash theme={null}
  npm cache clean --force
  npx bmad-method@latest install
  ```
</Warning>

## Uninstalling

Remove BMad Method from your project.

### Interactive Uninstall

```bash theme={null}
npx bmad-method uninstall
```

Choose what to remove:

* Specific modules
* IDE integrations
* Complete uninstall

### Complete Uninstall

Manually remove all BMad files:

```bash theme={null}
# 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

<Tabs>
  <Tab title="Node Version">
    **Error:** `BMad Method requires Node.js v20 or higher`

    **Solution:**

    ```bash theme={null}
    # Check version
    node --version

    # Update Node.js
    nvm install 20
    nvm use 20
    ```
  </Tab>

  <Tab title="Permission Errors">
    **Error:** `EACCES: permission denied`

    **Solution:**

    ```bash theme={null}
    # 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
    ```
  </Tab>

  <Tab title="Stale Cache">
    **Error:** Getting an old version

    **Solution:**

    ```bash theme={null}
    # Clear npm cache
    npm cache clean --force

    # Use specific version
    npx bmad-method@6.0.4 install
    ```
  </Tab>

  <Tab title="Network Issues">
    **Error:** `ETIMEDOUT` or network errors

    **Solution:**

    ```bash theme={null}
    # 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
    ```
  </Tab>
</Tabs>

### Slash Commands Not Working

<Steps>
  <Step title="Verify IDE integration">
    Check that your IDE's command directory exists:

    ```bash theme={null}
    # Claude Code
    ls -la .claude/commands/bmad

    # Cursor
    ls -la .cursor/commands/bmad
    ```
  </Step>

  <Step title="Restart your IDE">
    Close and reopen your AI IDE to reload command files.
  </Step>

  <Step title="Reinstall IDE integration">
    ```bash theme={null}
    npx bmad-method install --action update
    # Select your IDE again
    ```
  </Step>

  <Step title="Check IDE compatibility">
    Ensure your IDE version supports custom commands. Update to the latest version.
  </Step>
</Steps>

### Agents Not Responding

<Tabs>
  <Tab title="Check Agent Files">
    ```bash theme={null}
    ls -la _bmad/bmm/agents/
    ```

    Verify agent files exist (`.md` format).
  </Tab>

  <Tab title="Recompile Agents">
    ```bash theme={null}
    npx bmad-method install --action compile-agents
    ```
  </Tab>

  <Tab title="Check Configuration">
    ```bash theme={null}
    cat _bmad/core/config.yaml
    ```

    Verify configuration is valid YAML.
  </Tab>
</Tabs>

### Installation Hangs

<Warning>
  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
</Warning>

### Module Not Found

**Error:** `Module 'bmm' not found`

**Solution:**

```bash theme={null}
# 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:

```bash theme={null}
# 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:

```bash theme={null}
# 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:

```bash theme={null}
monorepo/
├── _bmad/              # Shared BMad installation
├── packages/
│   ├── app-1/
│   └── app-2/
└── package.json
```

## Getting Help

<CardGroup cols={2}>
  <Card title="Discord Community" icon="discord" href="https://discord.gg/gk8jAdXWmj">
    Get help from the community and BMad team
  </Card>

  <Card title="GitHub Issues" icon="github" href="https://github.com/bmad-code-org/BMAD-METHOD/issues">
    Report bugs and request features
  </Card>

  <Card title="Documentation" icon="book" href="https://docs.bmad-method.org">
    Browse the complete documentation site
  </Card>

  <Card title="YouTube" icon="youtube" href="https://www.youtube.com/@BMadCode">
    Watch tutorials and master classes
  </Card>
</CardGroup>

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

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

***

<Tip>
  Remember: `/bmad-help` is your intelligent guide. Use it anytime you're unsure what to do next!
</Tip>