|
| 1 | +--- |
| 2 | +title: 'Install Custom and Community Modules' |
| 3 | +description: Install third-party modules from the community registry, Git repositories, or local paths |
| 4 | +sidebar: |
| 5 | + order: 3 |
| 6 | +--- |
| 7 | + |
| 8 | +Use the BMad installer to add modules from the community registry, third-party Git repositories, or local file paths. |
| 9 | + |
| 10 | +## When to Use This |
| 11 | + |
| 12 | +- Installing a community-contributed module from the BMad registry |
| 13 | +- Installing a module from a third-party Git repository (GitHub, GitLab, Bitbucket, self-hosted) |
| 14 | +- Testing a module you are developing locally with BMad Builder |
| 15 | +- Installing modules from a private or self-hosted Git server |
| 16 | + |
| 17 | +:::note[Prerequisites] |
| 18 | +Requires [Node.js](https://nodejs.org) v20+ and `npx` (included with npm). Custom and community modules can be selected during a fresh install or added to an existing installation. |
| 19 | +::: |
| 20 | + |
| 21 | +## Community Modules |
| 22 | + |
| 23 | +Community modules are curated in the [BMad plugins marketplace](https://github.com/bmad-code-org/bmad-plugins-marketplace). They are organized by category and are pinned to an approved commit for safety. |
| 24 | + |
| 25 | +### 1. Run the Installer |
| 26 | + |
| 27 | +```bash |
| 28 | +npx bmad-method install |
| 29 | +``` |
| 30 | + |
| 31 | +### 2. Browse the Community Catalog |
| 32 | + |
| 33 | +After selecting official modules, the installer asks: |
| 34 | + |
| 35 | +``` |
| 36 | +Would you like to browse community modules? |
| 37 | +``` |
| 38 | + |
| 39 | +Select **Yes** to enter the catalog browser. You can: |
| 40 | + |
| 41 | +- Browse by category |
| 42 | +- View featured modules |
| 43 | +- View all available modules |
| 44 | +- Search by keyword |
| 45 | + |
| 46 | +### 3. Select Modules |
| 47 | + |
| 48 | +Pick modules from any category. The installer shows descriptions, versions, and trust tiers. Already-installed modules are pre-checked for update. |
| 49 | + |
| 50 | +### 4. Continue with Installation |
| 51 | + |
| 52 | +After selecting community modules, the installer proceeds to custom sources, then tool/IDE configuration and the rest of the install flow. |
| 53 | + |
| 54 | +## Custom Sources (Git URLs and Local Paths) |
| 55 | + |
| 56 | +Custom modules can come from any Git repository or a local directory on your machine. The installer resolves the source, analyzes the module structure, and installs it alongside your other modules. |
| 57 | + |
| 58 | +### Interactive Installation |
| 59 | + |
| 60 | +During installation, after the community module step, the installer asks: |
| 61 | + |
| 62 | +``` |
| 63 | +Would you like to install from a custom source (Git URL or local path)? |
| 64 | +``` |
| 65 | + |
| 66 | +Select **Yes**, then provide a source: |
| 67 | + |
| 68 | +| Input Type | Example | |
| 69 | +| --------------------- | ------------------------------------------------- | |
| 70 | +| HTTPS URL (any host) | `https://github.com/org/repo` | |
| 71 | +| HTTPS URL with subdir | `https://github.com/org/repo/tree/main/my-module` | |
| 72 | +| SSH URL | `git@github.com:org/repo.git` | |
| 73 | +| Local path | `/Users/me/projects/my-module` | |
| 74 | +| Local path with tilde | `~/projects/my-module` | |
| 75 | + |
| 76 | +The installer clones the repository (for URLs) or reads directly from disk (for local paths), then presents the discovered modules for selection. |
| 77 | + |
| 78 | +### Non-Interactive Installation |
| 79 | + |
| 80 | +Use the `--custom-source` flag to install custom modules from the command line: |
| 81 | + |
| 82 | +```bash |
| 83 | +npx bmad-method install \ |
| 84 | + --directory . \ |
| 85 | + --custom-source /path/to/my-module \ |
| 86 | + --tools claude-code \ |
| 87 | + --yes |
| 88 | +``` |
| 89 | + |
| 90 | +When `--custom-source` is provided without `--modules`, only core and the custom modules are installed. To include official modules as well, add `--modules`: |
| 91 | + |
| 92 | +```bash |
| 93 | +npx bmad-method install \ |
| 94 | + --directory . \ |
| 95 | + --modules bmm \ |
| 96 | + --custom-source https://gitlab.com/myorg/my-module \ |
| 97 | + --tools claude-code \ |
| 98 | + --yes |
| 99 | +``` |
| 100 | + |
| 101 | +Multiple sources can be comma-separated: |
| 102 | + |
| 103 | +```bash |
| 104 | +--custom-source /path/one,https://github.com/org/repo,/path/two |
| 105 | +``` |
| 106 | + |
| 107 | +## How Module Discovery Works |
| 108 | + |
| 109 | +The installer uses two modes to find installable modules in a source: |
| 110 | + |
| 111 | +| Mode | Trigger | Behavior | |
| 112 | +| --------- | ------------------------------------------------- | -------------------------------------------------------------------------------------------- | |
| 113 | +| Discovery | Source contains `.claude-plugin/marketplace.json` | Lists all plugins from the manifest; you pick which to install | |
| 114 | +| Direct | No marketplace.json found | Scans the directory for skills (subdirectories with `SKILL.md`), resolves as a single module | |
| 115 | + |
| 116 | +Discovery mode is typical for published modules. Direct mode is convenient when pointing at a skills directory during local development. |
| 117 | + |
| 118 | +:::note[About `.claude-plugin/`] |
| 119 | +The `.claude-plugin/marketplace.json` path is a standard convention adopted across multiple AI tool installers for plugin discoverability. It does not require Claude, does not use Claude APIs, and has no effect on which AI tool you use. Any module with this file can be discovered by any installer that follows the convention. |
| 120 | +::: |
| 121 | + |
| 122 | +## Local Development Workflow |
| 123 | + |
| 124 | +If you are building a module with [BMad Builder](https://github.com/bmad-code-org/bmad-builder), you can install it directly from your working directory: |
| 125 | + |
| 126 | +```bash |
| 127 | +npx bmad-method install \ |
| 128 | + --directory ~/my-project \ |
| 129 | + --custom-source ~/my-module-repo/skills \ |
| 130 | + --tools claude-code \ |
| 131 | + --yes |
| 132 | +``` |
| 133 | + |
| 134 | +Local sources are referenced by path, not copied to a cache. When you update your module source and reinstall, the installer picks up the latest changes. |
| 135 | + |
| 136 | +:::caution[Source Removal] |
| 137 | +If you delete the local source directory after installation, the installed module files in `_bmad/` are preserved. The module will be skipped during updates until the source path is restored. |
| 138 | +::: |
| 139 | + |
| 140 | +## What You Get |
| 141 | + |
| 142 | +After installation, custom modules appear in `_bmad/` alongside official modules: |
| 143 | + |
| 144 | +``` |
| 145 | +your-project/ |
| 146 | +├── _bmad/ |
| 147 | +│ ├── core/ # Built-in core module |
| 148 | +│ ├── bmm/ # Official module (if selected) |
| 149 | +│ ├── my-module/ # Your custom module |
| 150 | +│ │ ├── my-skill/ |
| 151 | +│ │ │ └── SKILL.md |
| 152 | +│ │ └── module-help.csv |
| 153 | +│ └── _config/ |
| 154 | +│ └── manifest.yaml # Tracks all modules, versions, and sources |
| 155 | +└── ... |
| 156 | +``` |
| 157 | + |
| 158 | +The manifest records the source of each custom module (`repoUrl` for Git sources, `localPath` for local sources) so that quick updates can locate the source again. |
| 159 | + |
| 160 | +## Updating Custom Modules |
| 161 | + |
| 162 | +Custom modules participate in the normal update flow: |
| 163 | + |
| 164 | +- **Quick update** (`--action quick-update`): Refreshes all modules from their original sources. Git-based modules are re-fetched; local modules are re-read from their source path. |
| 165 | +- **Full update**: Re-runs module selection so you can add or remove custom modules. |
| 166 | + |
| 167 | +## Creating Your Own Modules |
| 168 | + |
| 169 | +Use [BMad Builder](https://github.com/bmad-code-org/bmad-builder) to create modules that others can install: |
| 170 | + |
| 171 | +1. Run `bmad-module-builder` to scaffold your module structure |
| 172 | +2. Add skills, agents, and workflows with the various bmad builder tools |
| 173 | +3. Publish to a Git repository or share the folder collection |
| 174 | +4. Others install with `--custom-source <your-repo-url>` |
| 175 | + |
| 176 | +For modules to support discovery mode, include a `.claude-plugin/marketplace.json` in your repository root (this is a cross-tool convention, not Claude-specific). See the [BMad Builder documentation](https://github.com/bmad-code-org/bmad-builder) for the marketplace.json format. |
| 177 | + |
| 178 | +:::tip[Testing Locally First] |
| 179 | +During development, install your module with a local path to iterate quickly before publishing to a Git repository. |
| 180 | +::: |
0 commit comments