BeadsViewer — Summary

BeadsViewer (jeremyconkin/BeadsViewer) is a local Next.js 14 web application that provides a kanban board and tree view for Beads (bd) task graphs. It is a community tool (not from the Beads maintainers), reads all data via the bd CLI (bd list --json, bd show, bd update), and has no database of its own. The app exposes a Next.js API layer that shells out to bd commands, making it purely a read/write UI over the existing .beads/ Dolt database. Stack: Next.js 14 (App Router), TypeScript, shadcn/ui (Radix + Tailwind), react-dnd for kanban drag-and-drop, Sonner for toasts. Runs on port 3000. This is a Tier B framework — it has no prompts, no hooks, no agent instructions, only a UI specification and a working Next.js codebase. Compared to seeds, it is closest to claude-conductor's dashboard concept but focused exclusively on Beads issue visualization rather than agent orchestration.

BeadsViewer — Overview

Origin

Community tool by jeremyconkin, built on the BeadsViewer specification (SPEC.md). Not affiliated with the Beads maintainers (gastownhall / steveyegge). 0 GitHub stars, created as a personal utility.

Philosophy

"Browse to any project directory with a .beads/ folder and interact with your issues through a kanban board or tree view." No agent integration, no memory, no prompts — pure visualization layer.

Why bd CLI instead of direct Dolt access

From SPEC.md:

The bd CLI is the supported interface; all commands accept --json for machine-readable output.
Avoids importing Dolt as a dependency or reverse-engineering the schema.
The CLI handles validation, defaults, and business logic.

Features

• Kanban board with drag-and-drop to change task status
• Tree view for compact list of all tasks
• Filtering by status, priority, type, labels, and free-text search
• Task editing via detail dialog (title, description, status, priority, type, labels, assignee, due date, notes)
• Directory picker to switch between beads projects
• Persists last-used directory in localStorage

BeadsViewer — Architecture

Distribution

Standalone Next.js application. No npm package, no plugin.

Install

git clone https://github.com/jeremyconkin/BeadsViewer.git
cd BeadsViewer
npm install
npm run dev

Open http://localhost:3000, paste path to beads-enabled project.

Prerequisites

• Node.js 18+
• bd (Beads CLI) installed and on PATH
• At least one project with bd init already run

Architecture

Browser (React Client)
  ├── KanbanView (react-dnd drag-and-drop)
  ├── TreeView (filtered flat list)
  └── TaskDetailDialog (inline editing)
            ↕ fetch()
Next.js API Routes (/api/beads/*)
  ├── GET  /api/beads?dir=...      → bd list --json
  ├── GET  /api/beads/:id?dir=...  → bd show --json
  ├── PUT  /api/beads/:id          → bd update
  └── POST /api/directory/validate
            ↕ child_process.execFile
bd CLI (beads)
  └── .beads/embeddeddolt/ (Dolt database, source of truth)

Tech Stack

State Management

React state + context (no Redux, no Zustand). Sufficient for single-user local app.

Port

3000 (Next.js default dev server)

BeadsViewer — Components

Views (2)

API Routes (4)

Task Detail Dialog

Editable fields: title, description, status, priority, type, labels, assignee, due date, notes.

No Hooks / Skills / Agents

This is a pure UI application. No agent integration.

BeadsViewer — Uniqueness

Differs From Seeds

No analog in the 11 seeds. It is the only pure local web dashboard in this batch, and it is a companion app to beads-yegge rather than a standalone framework. The closest conceptual analog is the claude-mem web viewer (port 37777) but that is bundled into a memory plugin; BeadsViewer is a separate, standalone application.

Positioning

BeadsViewer demonstrates the ecosystem effect of a well-designed CLI-first tool: because bd outputs --json, any developer can build a UI without reverse-engineering the storage format. The app has zero dependencies on Dolt internals.

Observable Failure Modes

1. bd CLI dependency: If bd is not on PATH, all API routes fail.
2. Port conflict: Port 3000 may be occupied by other Next.js projects.
3. Dev server only: No production build optimization; intended for personal local use only.