beadboard/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

What Is BeadBoard

BeadBoard is a Windows-native local dashboard for the Beads issue tracker. It reads .beads/issues.jsonl files directly from repos and renders them as an agent-first operations console: a unified shell with Social, Graph, and Activity lenses for monitoring multi-agent work, managing swarms, and intervening on blockers. It supports multi-project aggregation, real-time file watching with SSE, and swarm/archetype coordination.

Active UX implementation spec: docs/plans/2026-02-28-ux-redesign-synthesis-prd.md

Commands

npm run dev          # Start Next.js dev server (localhost:3000)
npm run build        # Production build
npm run typecheck    # tsc --noEmit
npm run lint         # eslint
npm run test         # Runs all tests (explicitly enumerated in package.json)

Run a single test:

node --import tsx --test tests/lib/parser.test.ts

New test files must be added to the test script in package.json — the suite is explicitly enumerated, not auto-discovered.

Verification gates (run before closing any code bead)

npm run typecheck && npm run lint && npm run test

Architecture

Stack: Next.js 15 (App Router) · React 19 · Tailwind CSS · TypeScript (strict) · @xyflow/react (graphs) · Dagre (layout) · Chokidar (file watching) · Remotion (video generation)

Data flow

1. Source of truth: .beads/issues.jsonl files on disk, mutated only via bd CLI commands.
2. Parser (src/lib/parser.ts): Reads JSONL, normalizes dependencies and fields into BeadIssue objects.
3. Aggregate read (src/lib/aggregate-read.ts): Merges issues across multiple project roots based on project scope/mode.
4. Realtime (src/lib/realtime.ts): IssuesEventBus singleton dispatches change events. SSE endpoint (src/app/api/events/route.ts) streams them to the browser.
5. Watcher (src/lib/watcher.ts): Chokidar-based IssuesWatchManager watches JSONL + WAL + .last_touched files, coalesces events via ProjectEventCoalescer, and emits through the event bus. Snapshot diffing detects per-issue changes.
6. Writeback (src/lib/writeback.ts): API mutations write back to JSONL through bd-compatible paths.

Key directories

• src/app/ — Next.js App Router pages and API routes
  • / — Primary entry point. UnifiedShell with query-param-driven views: ?view=social|graph|activity
  • /graph, /sessions, /timeline — Legacy routes. Still exist but are not linked from the unified shell. Do not add new features here; migrate functionality into the unified shell instead.
  • /api/beads/ — CRUD endpoints for beads (create, read, update, close, reopen, comment)
  • /api/events/ — SSE endpoint for real-time updates
  • /api/swarm/ — Swarm coordination endpoints (create, launch, join, leave, status, templates)
  • /api/mission/ — Mission/epic management endpoints
  • /api/agents/ — Agent registry endpoints
• src/components/ — UI components organized by feature (kanban, graph, sessions, swarm, shared, activity, etc.)
  • shared/unified-shell.tsx — Root layout. Top bar, left panel, middle content (view-switched), right panel, thread drawer
  • shared/left-panel.tsx — Navigation spine: view switcher (Social/Graph/Activity), epic tree, filters
  • shared/top-bar.tsx — Global header: identity, health, blocked triage, metric tiles
  • activity/contextual-right-panel.tsx — Right panel content router (branches on URL context)
  • activity/activity-panel.tsx — Activity/telemetry feed (also used as the activity view content)
  • graph/smart-dag.tsx — DAG renderer using @xyflow/react + Dagre
  • social/social-page.tsx — Social lens: grouped task cards with dependency/thread context
• src/lib/ — Core logic (parser, types, pathing, watcher, realtime, registry, scanner, mutations, graph layout)
  • types.ts — Central type definitions (BeadIssue, BeadStatus, ProjectContext, etc.)
  • pathing.ts — Windows path canonicalization (drive letter normalization, path keys)
  • bd-path.ts — Resolves the bd CLI binary path
• src/hooks/ — React hooks for subscriptions (use-beads-subscription, use-swarm-list, use-url-state, etc.)
• components/ui/ — shadcn/ui primitives
• tests/ — Node.js native test runner with tsx loader; mirrors src structure
• scripts/ — CLI utilities (bb.ts — BeadBoard CLI, Playwright capture scripts)
• docs/ — RFCs, ADRs, protocols, and feature specs

Path alias

@/* maps to the project root (configured in tsconfig.json).

Windows considerations

• All path handling must canonicalize Windows paths (drive letter casing, backslash normalization). Use canonicalizeWindowsPath and windowsPathKey from src/lib/pathing.ts.
• Webpack filesystem cache is disabled in dev mode (next.config.ts) to avoid Windows ENOENT errors.

ESLint config

@typescript-eslint/no-explicit-any and prefer-const are intentionally turned off. eslint.config.mjs uses flat config with next/core-web-vitals and next/typescript.

Beads workflow

Use bd as the sole interface for mutating beads. Never write to .beads/issues.jsonl directly. See AGENTS.md for the full operating manual including dependency discipline, parallel agent patterns, and session completion protocol.