From 06a6965fa9c9a0066b270034f0a4c7ea19a4fcdf Mon Sep 17 00:00:00 2001 From: zenchantlive Date: Thu, 26 Feb 2026 10:34:43 -0800 Subject: [PATCH] docs: add CLAUDE.md for AI assistant context Documents BeadBoard architecture, commands, verification gates, data flow, key directories, and Windows considerations for AI assistants working on this codebase. --- CLAUDE.md | 84 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 84 insertions(+) create mode 100644 CLAUDE.md diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..372157f --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,84 @@ +# 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](https://github.com/steveyegge/beads) issue tracker. It reads `.beads/issues.jsonl` files directly from repos and renders them as interactive Kanban boards and dependency graphs. It supports multi-project aggregation, real-time file watching with SSE, and agent/swarm coordination. + +## Commands + +```bash +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: +```bash +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) + +```bash +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 + - `/` — Kanban dashboard (main page) + - `/graph` — Dependency graph explorer using @xyflow/react + Dagre + - `/sessions` — Agent session management + - `/timeline` — Timeline view + - `/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, etc.) + - `shared/unified-shell.tsx` — Main layout shell wrapping all pages (top bar, left panel, right panel) +- `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.