beads-visualizer

Visual dashboard for monitoring beads issues and OpenSpec specifications.

Quick Start

``bash


Run from any directory with .beads/ or openspec/


npx beads-visualizer
`

The dashboard will automatically:
1. Find projects in the current directory
2. Start a local server
3. Open your browser

Features

- Project Discovery: Automatically finds projects with .beads/ or openspec/ directories
- Specifications Viewer: Browse OpenSpec capabilities, requirements, and scenarios
- Issues Dashboard: View beads issues with status, priority, and dependencies
- Dependency Graph: Interactive visualization of issue dependencies
- Live Updates: Real-time refresh when files change
- Works with partial setups: Shows only relevant tabs for beads-only or openspec-only projects

CLI Options

`
Usage: beads-visualizer [options]

Options:
-V, --version Output version number
-p, --port Port to run the server on (default: "3000")
--no-open Do not automatically open the browser
--path Path to scan for projects (defaults to current directory)
-h, --help Display help
`

$3

`bash


Use a specific port

npx beads-visualizer --port 8080

Scan a specific directory

npx beads-visualizer --path /path/to/projects

Run without opening browser (useful for CI/remote)

npx beads-visualizer --no-open
`

Project Detection

The dashboard looks for projects containing:
- .beads/ directory (beads issue tracking)
- openspec/ directory (OpenSpec specifications)

Either one is sufficient. Projects with both will show all features.

Scanning happens in:
1. Current directory
2. Immediate subdirectories
3. Parent directories (up to 3 levels)

Environment Variables

| Variable | Description | Default |
|----------|-------------|---------|
| PROJECTS_ROOT | Root directory to scan | Current directory |
| PORT | Server port | 3000 |

Docker

`bash


Using docker-compose

PROJECTS_DIR=/path/to/projects docker-compose up -d

Using docker directly

docker build -t beads-visualizer .
docker run -d -p 3000:3000 -v /path/to/projects:/projects:ro -e PROJECTS_ROOT=/projects beads-visualizer
`

Development

`bash


Clone and install

git clone https://github.com/vorlenko/Visualize-openspec-and-beads.git
cd Visualize-openspec-and-beads
npm install

Development server

npm run dev

Build for production

npm run build

Test locally

node dist/cli.js --path /path/to/project
``

License

MIT