beads-viz AGENTS.md

Agent Instructions — Beads Viz

Read-only task graph visualizer for Claude Desktop. MCP server (TypeScript/Node.js) wrapping the bd CLI, with a Svelte single-file UI bundle showing interactive DAG visualization, list view, and stats dashboard. Runs inside Claude Desktop as an MCP App (sandboxed iframe).

Quick Start

npm install
npm run build        # Build UI bundle + server
npm run dev          # Vite dev server (UI only, no MCP host)

Claude Desktop Configuration

Add to ~/.config/claude-desktop/config.json:

{
  "mcpServers": {
    "beads-viz": {
      "command": "node",
      "args": ["dist/server/index.js"],
      "cwd": "/path/to/your/beads-project"
    }
  }
}

The server discovers the Beads project by walking up from cwd to find .beads/config.yaml.

Architecture

Claude Desktop (MCP Host)
  ├── Chat conversation
  │     "Show me the task graph"
  │     → calls visualize-tasks tool
  ├── MCP Server (Node.js, stdio)
  │     ├── visualize-tasks → bd list --all --json → summary + tasks + ui ref
  │     ├── poll-tasks (app-only) → bd list --all --json → fresh data
  │     ├── show-task (app-only) → bd show <id> --json → task detail
  │     └── ui://beads-viz resource → serves dist/index.html
  └── Sandboxed iframe (MCP App)
        ├── Top Strip (project, stats pills, DAG/LIST/STATS tabs)
        ├── Canvas (DAG / List / Stats views)
        ├── Bottom Drawer (task detail on click)
        └── Polls server every 3s for fresh data

Key insight: The UI is read-only. All task mutations (claim, close, create) happen through the agent chat, not the UI.

Project Structure

src/
├── server/                 # MCP server (Node.js target)
│   ├── index.ts            # Entry point: McpServer + stdio transport
│   ├── tools.ts            # Tool registrations (visualize, poll, show)
│   ├── beads-client.ts     # bd CLI wrapper (execFile + JSON parse)
│   └── types.ts            # Server-side TypeScript types
└── ui/                     # Svelte app (browser target, Vite-bundled)
    ├── App.svelte           # Root: view switching, layout, keyboard
    ├── main.ts              # Svelte mount + MCP bridge init
    ├── app.css              # CSS variables, reset, animations
    ├── index.html           # Vite entry point
    ├── components/
    │   ├── TopStrip.svelte  # 32px strip: project, stats, tabs
    │   ├── DagView.svelte   # ELK.js DAG canvas + SVG edges
    │   ├── DagNode.svelte   # 156x42 node card with phase colors
    │   ├── ListView.svelte  # Status-grouped task list
    │   ├── StatsView.svelte # Progress ring, phase bars, velocity
    │   └── TaskDrawer.svelte # Bottom drawer with task details
    └── lib/
        ├── elk-layout.ts    # ELK.js layout computation
        ├── phase.ts         # 9-phase color system (dark + light)
        ├── stores.ts        # Svelte writable stores
        ├── mcp-bridge.ts    # MCP App SDK bridge (connect, poll, theme)
        └── types.ts         # UI-side TypeScript types