BMAD Dashboard

A local web dashboard that shows your BMAD project state in real time: current phase, artifacts, next steps, and sprint status. Use it from any BMAD project without copying code—run it with npx and it reads that project’s _bmad and _bmad-output automatically.

No database, no auth. Everything is file-based and local.

Features

• Phase overview — See where you are in the BMAD workflow (Analysis → Planning → Solutioning → Implementation) and which artifacts exist.
• Three views — Overview (phase cards, next steps, artifact details), Diagram (workflow with commands and agents), Kanban (user stories by status; enabled when you have stories).
• Live updates — The UI refreshes when you change BMAD files (file watcher + SSE). Manual Refresh and optional 60s polling fallback.
• Next steps — Recommended BMAD commands with one-click copy (e.g. /bmad-bmm-create-prd).
• Story details — Expand epics and stories to see user story text, acceptance criteria, and status from sprint-status.yaml.
• Light / dark theme — Theme toggle in the header; preference saved in localStorage.

Screenshots

Add PNG/JPEG files to docs/screenshots/ (see docs/screenshots/README.md for naming). The images below will appear once the files exist.

| Overview | Diagram | Kanban | |----------|---------|--------| | | | |

Overview: phase progress, artifacts, next steps. Diagram: workflow phases and commands. Kanban: stories by status.

Story detail (click a card in Kanban):

Requirements

• Node.js 18+ (20+ recommended)
• A BMAD project: a folder that contains (or will contain) _bmad/ and optionally _bmad-output/ (e.g. prd.md, architecture.md, epics.md, sprint-status.yaml).

Quick start

1. Open your BMAD project

cd /path/to/your-bmad-project

2. Run the dashboard

npx bmad-dashboard

You’ll see something like: BMAD dashboard at http://localhost:3000 and Project root: /path/to/your-bmad-project.

3. Open in the browser

Open http://localhost:3000. You’ll see the project name, phase progress, artifact checklist, next steps, and (if present) sprint status.

• Overview — Phase cards, next steps bar, and expandable artifact details (steps, acceptance criteria, commands).
• Diagram — Visual workflow: phases, artifacts, commands, and agents.
• Kanban — Enabled when user stories exist; columns by status (Backlog, Ready for dev, In progress, Review, Done). Click a card to see user story and acceptance criteria.

To stop: Ctrl+C in the terminal.

How it works

1. You run npx bmad-dashboard from inside a BMAD project (a folder that has or will have _bmad/ and _bmad-output/).
2. The dashboard starts a small server and serves the UI at http://localhost:3000 (or the port you set).
3. The server reads your project’s BMAD config and artifact files and serves a UI that updates when you change files (file watcher + live reload), or when you click Refresh.
4. Project root is the directory where you ran the command, so the dashboard always reflects that project’s state.

What the dashboard shows

| Section | Description | |--------|-------------| | Phase progress | Current BMAD phase and which phases are done (from your artifacts). | | Artifacts | Checklist: PRD, Architecture, Epics & stories, UX design, Sprint status (✓ = file exists). | | What’s inside each artifact | Expand to see source path, commands that build it, and for PRD/Architecture the list of steps (done/pending); for Epics/Sprint, stories with acceptance criteria and status. | | Next steps | Recommended BMAD workflows with the exact Cursor command (e.g. /bmad-bmm-create-prd). Click to copy. | | Sprint status | Table of story/epic IDs and status from _bmad-output/implementation-artifacts/sprint-status.yaml. | | Kanban | Stories grouped by status; click a card for user story and acceptance criteria. |

Other ways to run

Different port

PORT=4000 npx bmad-dashboard

Then open http://localhost:4000.

Different project (without changing directory)

BMAD_PROJECT_ROOT=/path/to/other-bmad-project npx bmad-dashboard

From a local clone (no npm install of the package)

1. Build once in the clone:

   cd /path/to/bmad-dashboard/dashboard
   npm install
   npm run build

2. From your BMAD project:

   cd /path/to/your-bmad-project
   npx /path/to/bmad-dashboard/dashboard

Troubleshooting

| Problem | What to do | |--------|------------| | “Could not load BMAD state” | The server didn’t start or isn’t reachable. Run npx bmad-dashboard from your project folder and ensure nothing is blocking the port (default 3000). | | Port 3000 already in use | Use another port: PORT=3001 npx bmad-dashboard, then open http://localhost:3001. On macOS/Linux: lsof -i :3000 then kill <PID>. | | Dashboard is empty or “no artifact details” | Your project may not have _bmad/ or _bmad-output/ yet. Run BMAD workflows (e.g. Create PRD) in Cursor to generate artifacts; the dashboard will show them after the next refresh. | | Wrong project shown | You ran the command from a different folder. cd to the correct BMAD project root and run again, or use BMAD_PROJECT_ROOT=/correct/path npx bmad-dashboard. | | Acceptance criteria not showing | Ensure your epics.md has a section like Acceptance Criteria: with list items (e.g. - **Given** ...). The parser supports several header and list formats. |

Development (for contributors)

To work on the dashboard itself (in this repo):

cd dashboard
npm install
npm run dev

• App: http://localhost:5173 (Vite). The API runs on port 3000; Vite proxies /api to it.
• Tests: npm run test (single run), npm run test:watch (watch).
• Lint: npm run lint, npm run lint:fix.
• Build: npm run build (output in dist/).

Structure: Server in server/ (config, fileUtils, constants, bmadState, artifactDetails, routes, fileWatch); frontend in src/ (constants, hooks, components, App).

Testing UI locally (no publish)

You don’t need to publish to npm to try UI changes. This repo is a BMAD project: it has _bmad/ and _bmad-output/ at the repo root.

1. From the repo root, open a terminal in the dashboard/ directory:

   cd dashboard
   npm install
   npm run dev

2. The API server resolves project root to the parent of dashboard/ (i.e. the bmad-dashboard repo root) when not run as an installed package. So it will load this repo’s _bmad-output/planning-artifacts/, sprint-status.yaml, etc.
3. Open http://localhost:5173 (Vite). You’ll see the dashboard with real data from this repo: PRD, Architecture, Epics, Kanban (if sprint status exists), and all three views (Overview, Diagram, Kanban).
4. Edit React/CSS in src/, save; Vite hot-reloads. Edit artifacts in _bmad-output/; the file watcher will refresh the API and the UI will update.

To use another BMAD project’s data without changing directory, run the dev server with:

BMAD_PROJECT_ROOT=/path/to/other-bmad-project npm run dev:server

Then run the client in another terminal (npm run dev:client in dashboard/). The API will read from other-bmad-project.

Automated releases (CI)

On every push to main, GitHub Actions:

1. Runs tests and lint in dashboard/.
2. If they pass, bumps the patch version, publishes to npm (using NPM_TOKEN or Trusted Publishers), and commits the version bump to main with chore(release): X.Y.Z [skip ci].
3. Creates a GitHub Release for the new version (tag vX.Y.Z) only when publish and push succeed.

Setup (one-time):
Option A — Granular token: Create a Granular access token on npm with read and write and Bypass 2FA. Add it as repo secret NPM_TOKEN (Settings → Secrets and variables → Actions).
Option B — Trusted Publishers (OIDC): Link npm to GitHub and set Trusted publishing for this package (workflow in .github/workflows/release.yml) on npmjs.com; leave NPM_TOKEN unset.

If the package doesn’t exist on npm yet, do one manual publish from your machine (cd dashboard && npm publish --access public), then configure the chosen option.

License

MIT