Installation

Picture your desk on a Monday morning. You have an idea, a terminal, and an AI coding agent that will happily write code all day — but no shared surface where you and that agent can see the same plan, the same stories, the same progress. BMAD Board is that surface: a visual cockpit for leading your hybrid team (you plus your AI agents) through real epics and stories using the BMAD method.

This page gets the app running and points it at a project. It takes about five minutes.

Prerequisite: BMAD Board is a cockpit, not the engine. It reads a project that already uses the BMAD method (a folder with a _bmad/ directory) and launches your own LLM CLI to do the work. Make sure the three prerequisites below are in place before you open a project.

Before you begin

You need three things. Each one plays a distinct role, so it helps to know why.

What	Why you need it	How to check
Node.js v18 or newer	BMAD Board is an Electron app; Node runs it.	`node --version`
An LLM CLI (e.g. Claude Code)	The board launches commands into this agent — it doesn't ship its own model.	`claude --version` (or your provider's CLI)
A BMAD project (a `_bmad/` folder)	The board reads your epics, stories, and config from here.	Look for `_bmad/` in your project root

1. Node.js (v18+)

Install Node.js if you don't have it. Verify the version:

node --version
# v18.x or higher

2. An LLM CLI

BMAD Board is deliberately model-agnostic. You bring the coding agent; the board orchestrates it. Any LLM CLI that supports the BMAD method works — for example, Claude Code (Anthropic's CLI — the reference experience).

The BMAD method itself is CLI-agnostic, so any coding agent that supports it works, as long as you can run it from a terminal — the board launches the agent's CLI in its embedded terminal. See Terminal & providers for the agents with first-class, built-in support. Install at least one and confirm it runs from your terminal. For Claude Code:

claude --version

You'll pick which provider a command uses later, from the terminal and providers panel — so it's fine to start with just one.

3. A project that uses the BMAD method

BMAD Board opens a folder, and it expects that folder to contain a _bmad/ directory — the installed BMAD tooling and configuration (config.toml, epics, stories). That _bmad/ folder is the signature of a BMAD-method project.

If you don't have one yet, that's fine — you can install the BMAD method into any project, greenfield or brownfield. The method itself is 100% open source, created by Brian Madison. Once a project has its _bmad/ folder, the board can read it.

Note: No _bmad/ folder means the board has nothing to visualise. See the troubleshooting list below if the board tells you a folder isn't a BMAD project yet.

Get BMAD Board

There are two ways to install: build from source (available today) or grab a packaged download (where available for your platform).

Option A — Clone and run from source

This is the reliable path on every platform that can run Node.

git clone https://github.com/joskoomen/bmad-board.git
cd bmad-board
npm install
npm start

npm install pulls the dependencies; npm start launches the app. That's it — a window opens.

If you want developer tools (an open DevTools panel, verbose logging), launch in dev mode instead:

npm run dev

Option B — Packaged download

BMAD Board can also be built into a native installer. If a packaged build is published for your platform, download it from the project's releases page and install it like any desktop app — no terminal required. Check the project's GitHub releases for what's currently available.

Note on platforms: BMAD Board runs on macOS today, with Windows and Linux on the roadmap. Building from source (Option A) works anywhere Node runs; native, signed installers currently target macOS first. If you're on Windows or Linux, the clone-and-run path is your best bet for now.

First launch

When BMAD Board opens for the first time, you'll see the app shell: a sidebar on the left for navigation and a large working area on the right. Because you haven't opened a project yet, the board is waiting for one — there are no epics or stories to show.

To open a project:

Use Open Project (from the welcome screen or the app's File / Go menu).
In the folder picker, navigate to your project's root — the folder that contains the _bmad/ directory (select the project folder itself, not the _bmad/ folder inside it).
Confirm.

BMAD Board scans _bmad/, discovers your epics and stories, and brings the Epics and Stories views to life. From here you're in the cockpit: a story lifecycle laid out visually, an embedded terminal ready to launch BMAD commands, and your documents a click away.

You can open more than one project at once — each lives in its own window — so a multi-project morning is no problem.

Troubleshooting

A few things trip people up on the first run. Here's how to clear them.

Symptom	Cause	Fix
"This folder isn't a BMAD project" (no epics appear)	The folder has no `_bmad/` directory.	You opened a plain project. Install the BMAD method into it first, or pick a folder that already has `_bmad/`. Double-check you selected the parent folder, not `_bmad/` itself.
"LLM CLI not found" when you click a story phase	The board can't find your coding agent on your `PATH`.	Install a supported CLI (e.g. Claude Code) and make sure it runs from your terminal. Then set or confirm your provider in Settings.
The window opens but stays empty	No project opened yet.	Use Open Project and choose a folder containing `_bmad/`.
`npm start` fails on install	Node is too old, or dependencies didn't install.	Confirm `node --version` is v18+, delete `node_modules`, and re-run `npm install`.

Tip: The provider a command runs with is a setting you control. If your agent lives at a custom path or you want to switch from Claude Code to another CLI, open Settings and set it there — you don't have to reinstall anything.

Next steps

You're installed and pointed at a project. Now let's take one real story all the way to Done.

Your first project — a guided first run through the story lifecycle.