# Board — Kanban for Claude Code

A local-first kanban board that orchestrates [Claude Code](https://docs.anthropic.com/en/docs/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

```bash
# 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:

```bash
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

```bash
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:

```bash
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:

```bash
BOARD_LOG_LEVEL=debug pnpm dev
```

### Watcher Interval

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

```bash
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.