Board

A local-first kanban board that orchestrates Claude Code task execution. Create tasks in the UI, Claude Code picks them up via MCP tools or the built-in watcher, creates branches and PRs, and you review and merge — all from a single dashboard.

Features

• Four-column board: Pending → In Progress → In Review → Done
• Two execution paths: Manual (Claude uses MCP tools) or Watcher (auto-spawns claude -p /next-task)
• Branch-per-task: Each task gets its own git branch and PR
• Token exhaustion handling: Watcher detects quota errors, pauses with countdown, auto-resumes on reset
• Single-user, local-only: Runs on 127.0.0.1, SQLite storage, zero external dependencies
• Serial execution: One task at a time for predictable, reviewable results

Prerequisites

• Node.js 20+
• pnpm 10+
• Claude Code CLI installed (claude on PATH)
• GitHub CLI (gh) installed and authenticated (gh auth login)

Quick Start

# Install dependencies
pnpm install

# Start the dev server
pnpm dev

# Open the board
open http://localhost:3000

On first launch, click + Project to register a git repository. Then create tasks and start the watcher.

MCP Installation

Register the Board MCP server with Claude Code so Claude can claim, submit, and query tasks:

claude mcp add board -- node /path/to/board/bin/mcp-server.ts

Or use the Settings page (/settings) in the UI — it shows the exact command with a copy button.

After registering, Claude Code can use these MCP tools:

Tool	Purpose
next-task	Claim the highest-priority pending task
submit-task	Submit work for review (creates PR metadata)
fail-task	Mark a task as failed with error details
get-task	Query a task by ID
list-tasks	List tasks with optional project/status filters
list-projects	List all registered projects
/board	Slash command — quick task listing

Development

pnpm dev          # Start Next.js dev server
pnpm build        # Production build
pnpm typecheck    # TypeScript type checking (strict mode)
pnpm lint         # ESLint
pnpm test         # Unit + integration tests (Vitest)
pnpm test:watch   # Tests in watch mode
pnpm test:e2e     # End-to-end tests (Playwright)

Database

The SQLite database lives at ~/.board/board.db by default. Override with:

BOARD_DB_PATH=/custom/path.db pnpm dev

Logs

Structured logs are written to ~/.board/logs/board.log via pino. Log level can be adjusted:

BOARD_LOG_LEVEL=debug pnpm dev

Watcher Interval

For testing or faster iteration, override the watcher tick interval:

BOARD_WATCHER_INTERVAL_MS=5000 pnpm dev   # 5s instead of 60s default

Architecture

Browser → Next.js Server (HTTP API + UI) → SQLite (WAL mode)
                    ↕ shared lib/core
          bin/mcp-server.ts ← Claude Code (stdio MCP)

Core design principles:

1. Protocol-agnostic core — lib/core/ contains all business logic (state machine, repos). MCP and HTTP API are thin adapters over the same core.
2. Symmetric triggers — Manual slash commands and watcher spawns follow the same task lifecycle.
3. Local-first — Listens on 127.0.0.1, SQLite single-file DB, no cloud dependencies.

Project Structure

app/
  (ui)/             Board UI (page, settings, projects/new)
  api/              REST API routes
components/
  board/            Board-specific components
  ui/               UI primitives (Button, Input, etc.)
lib/
  core/             Protocol-agnostic core (state machine, repos, git, db)
  mcp/              MCP server implementation
  watcher/          Watcher scheduler + token detection
  api/              API client + response helpers
  hooks/            React hooks (SWR-based)
bin/
  mcp-server.ts     MCP entry point (Claude Code subprocess)
db/
  schema.ts         Drizzle ORM schema
tests/
  unit/             Unit tests
  integration/      API integration tests
  e2e/              Playwright E2E tests

Testing

• Unit tests (tests/unit/): Core logic — state machine, repos, detection patterns
• Integration tests (tests/integration/): API routes with real SQLite
• E2E tests (tests/e2e/): Full Playwright scenarios including watcher + token pause

E2E tests use stub claude and gh binaries to simulate Claude Code and GitHub CLI without real API calls.

Tech Stack

Layer	Technology
Framework	Next.js 15 (App Router) + React 19
Language	TypeScript 5.x (strict mode)
UI	Tailwind CSS v4
Data Fetching	SWR
ORM	Drizzle ORM
Database	SQLite (better-sqlite3, WAL mode)
Validation	Zod
Logging	pino
Testing	Vitest + Playwright
Package Manager	pnpm

License

Private project.