beads-viz

[](https://www.npmjs.com/package/beads-viz) [](https://github.com/pyros-projects/beads-viz/blob/main/LICENSE)

Read-only task graph visualizer for Beads projects. Runs as an MCP App inside Claude Desktop or VS Code Copilot, showing an interactive DAG, list view, and stats dashboard.

Claude Desktop / VS Code Copilot
  ├── Chat: "Show me the task graph"
  │     → calls visualize-tasks tool
  ├── MCP Server (Node.js, stdio)
  │     ├── visualize-tasks → bd list --all --json
  │     ├── poll-tasks      → fresh data every 3s
  │     ├── show-task        → task detail by ID
  │     └── ui://beads-viz  → serves the UI bundle
  └── Sandboxed iframe (MCP App)
        ├── DAG view (ELK.js layered layout)
        ├── List view (status-grouped)
        ├── Stats dashboard (progress, velocity)
        └── Task detail drawer

The UI is read-only — all task mutations (create, claim, close) happen through agent chat.

• Node.js >= 18 (22+ recommended)
• npm >= 9
• Beads CLI (bd) installed and on PATH — install instructions
• A Beads project (directory containing .beads/config.yaml)

Verify your setup:

node --version    # v18.0.0+
bd --version      # any version
bd list --json    # should output JSON (run from a Beads project)

The fastest way — no cloning, no building. Just configure your MCP host to use npx:

{
  "mcpServers": {
    "beads-viz": {
      "command": "npx",
      "args": ["-y", "beads-viz"],
      "cwd": "/path/to/your/beads-project"
    }
  }
}

npx downloads and caches the package on first run. The -y flag skips the install confirmation prompt.

> Where does this go? See the Installation section below for the config file location for your setup (C