beads-dashboard

A visual dashboard for the beads issue tracker. Dark-mode-first React UI with live updates, multiple views, keyboard navigation, and drag-and-drop Kanban.

The dashboard features a dark theme (with optional light mode), four views (tree, activity feed, pipeline/kanban, dependency graph), real-time WebSocket updates, a slide-out detail panel with Markdown rendering, and full keyboard navigation.

Features

• Live Updates -- WebSocket connection watches .beads/ for file changes and pushes refresh events; falls back to 10-second polling
• Tree View -- Collapsible hierarchy with bead ID, title, status/priority badges, assignee, and completion percentage on parent nodes
• Activity Feed -- Recent changes sorted by timestamp, agent cards showing who is working on what
• Pipeline/Kanban -- Drag-and-drop cards between Open, In Progress, Blocked, and Closed columns
• Dependency Graph -- Interactive Mermaid diagram with zoom, pan, and click-to-select
• Detail Panel -- Slide-out panel with full description (rendered Markdown), dependencies, dependents, labels, dates, comments, and inline editing
• Filtering & Search -- Multi-select dropdowns for status, priority, type, and assignee; full-text search; sort by updated/created/priority/status; filters persist in URL params
• Keyboard Navigation -- j/k to move, Enter to open, Escape to close, / to search, n for new bead, 1-4 to switch views, ? for help
• New Bead Creation -- Modal with title, priority, type, description (Markdown), dependency multi-select, and live preview
• Agent Fleet Visibility -- Agent cards showing claimed beads, active work indicator
• Dark/Light Mode -- Toggle between themes; preference saved to localStorage
• Progress Tracking -- Summary stats and completion progress bar

Installation

Install from the local directory:

pip install /path/to/beads-dashboard

Or in development mode:

pip install -e /path/to/beads-dashboard

Eventually (once published):

pip install beads-dashboard

Usage

Run from any directory that contains (or is a child of) a .beads/ directory:

beads-dashboard --open

Options

--port PORT       Port to serve on (default: 8099)
--beads-dir DIR   Directory containing .beads/ (default: auto-discover from cwd)
--open            Auto-open the dashboard in the default browser

Examples

# Start on a custom port
beads-dashboard --port 9000

# Point to a specific beads project
beads-dashboard --beads-dir /path/to/my/project

# Start and auto-open in browser
beads-dashboard --open

Keyboard Shortcuts

Key	Action
?	Toggle keyboard shortcuts help
/	Focus search input
n	Open new bead form
1	Switch to Tree view
2	Switch to Activity view
3	Switch to Pipeline view
4	Switch to Graph view
j / Down	Move down in list
k / Up	Move up in list
Enter	Open detail panel for selected bead
Esc	Close panel / modal / overlay

API Endpoints

The Python server exposes these endpoints (all backed by bd CLI commands):

Method	Path	Description
GET	/api/beads	All beads as JSON
GET	/api/mermaid	Mermaid dependency diagram
GET	/api/status	Status summary text
GET	/api/config	Server config (WebSocket port)
GET	/api/bead/{id}	Single bead detail
GET	/api/bead/{id}/deps	Dependency tree for a bead
GET	/api/bead/{id}/comments	Comments for a bead
POST	/api/bead	Create a new bead
POST	/api/bead/{id}/comment	Add a comment
POST	/api/bead/{id}/close	Close a bead
POST	/api/bead/{id}/reopen	Reopen a bead
PATCH	/api/bead/{id}	Update status, priority, description, or claim
WS	ws://localhost:{port+1}	WebSocket for live update events

Development

Prerequisites

• Python 3.9+
• Node.js 18+ (for frontend development only)
• bd CLI tool installed and on PATH

Frontend Development

cd src/frontend

# Install dependencies
npm install

# Build to static output (served by Python)
npm run build

# Or run Vite dev server (proxies API to Python server)
npm run dev

The Vite build outputs to src/beads_dashboard/static/, which is committed to the repo and served by the Python HTTP server. Users installing via pip never need Node.js.

Python Server

# Install in development mode
pip install -e .

# Run the server
beads-dashboard --port 8099 --open

Architecture

src/
  beads_dashboard/          Python package
    server.py               HTTP server + API endpoints + WebSocket server
    static/                 Vite build output (committed)
  frontend/                 React/Vite source (dev only)
    src/
      App.jsx               Main app with state management
      components/           React components
      styles/               CSS

The Python server uses only the standard library plus websockets. All UI mutations go through bd CLI commands via subprocess. The WebSocket server polls .beads/ for file modification times and broadcasts refresh events to connected clients.

Requirements

• Python 3.9+
• websockets Python package (installed automatically)
• bd CLI tool installed and on PATH

License

MIT