pyros-projects/beads-viz
Read-only task graph visualizer for Beads projects — MCP App for Claude Desktop and VS Code Copilot
[](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 drawerThe UI is read-only — all task mutations (create, claim, close) happen through agent chat.
bd) installed and on PATH — install instructions.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
Loading reviews...