BMAD Studio

Visual workflow dashboard for the BMAD Method.

Prerequisites

• Node.js >= 18
• pnpm

Install

pnpm install

Development

Start both the server (port 5400) and UI (port 5173):

pnpm dev

Open http://localhost:5173

Testing Scenarios

1. Normal Mode (BMAD project detected)

Run from the project root — the server auto-detects _bmad-output/:

cd /path/to/bmad-studio
pnpm dev

You should see the Subway Map view.

2. Unconfigured Mode (No BMAD project detected)

To trigger the first-launch ConfigScreen, run the server from an empty directory:

# Terminal 1 — server from empty dir
mkdir -p /tmp/bmad-test
cd /tmp/bmad-test
npx tsx /path/to/bmad-studio/packages/server/src/dev.ts

cd /Volumes/jaabiri/bmad-studio && npx tsx /Volumes/jaabiri/bmad-studio/packages/server/src/dev.ts
 cd /Volumes/jaabiri/bmad-studio && pnpm --filter @bmad-studio/ui dev

 cd /Volumes/jaabiri/bmad-studio && pnpm --filter @bmad-studio/server dev
# Terminal 2 — UI dev server
cd /path/to/bmad-studio
pnpm --filter @bmad-studio/ui dev

Open http://localhost:5173 — you will see the "No BMAD project detected" screen.

From here you can:

• Type a directory name (e.g. _bmad-output) and click Configure — the server creates the directory and transitions to the Subway Map
• If suggestions appear (directories containing .md files), click one to select it

3. Kill Running Servers

If ports are already in use:

# Find and kill processes on ports 5400 and 5173
lsof -ti :5400 -ti :5173 | xargs kill

Run Tests

# All server tests
pnpm --filter @bmad-studio/server test

# All CLI tests
pnpm --filter @bmad-studio/cli test

# All UI tests
pnpm --filter @bmad-studio/ui test

Project Structure

packages/
  cli/        # CLI launcher (bmad-studio command)
  server/     # Express API server (port 5400)
  shared/     # Shared types and constants
  ui/         # React frontend (Vite + TanStack Router)