beads-visualizer

Visual dashboard for monitoring beads issues and OpenSpec specifications.

Quick Start

# 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>  Port to run the server on (default: "3000")
  --no-open          Do not automatically open the browser
  --path <path>      Path to scan for projects (defaults to current directory)
  -h, --help         Display help

Examples

# 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

# 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

# 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