Work Board

Local work-tracking board with AI-powered features. Manage tasks, auto-discover git projects, and launch Claude directly into any project from the board.

| Layer | Tech | Port | |-------|------|------| | Frontend | Nuxt 3 + Vue 3 + Tailwind CSS | 7750 | | Backend | NestJS + Prisma v7 + Kysely | 7749 | | Database | PostgreSQL | 5433 (host) | | Real-time | socket.io WebSocket | — | | AI | Claude CLI | — |

Features

• Work items — create, edit, archive, reorder by status/priority/project
• Git project discovery — auto-scans your PROJECTS_ROOT for git repos
• Start Work — one click opens a cmux workspace in the project directory and launches Claude
• Session resume — clicking Start Work again on an in-progress card focuses the existing workspace instead of creating a new one
• AI Smart Create — paste raw text (ticket, email, note) and AI extracts a structured work item
• AI Suggest — auto-suggest priority and tags
• AI Summary — board-wide status overview
• Real-time sync — all open browser tabs stay in sync via WebSocket
• View modes — Normal, Recent, By Project, By Priority

Requirements

• Node.js 20+
• Yarn 4+ (corepack enable)
• PostgreSQL 14+ — run locally or via Docker (docker compose up -d)
• Claude CLI — npm i -g @anthropic-ai/claude-code and authenticated
• oh-my-claudecode — npm i -g oh-my-claudecode (auto-installed by yarn setup)
• cmux — cmux.com (macOS terminal app) for the Start Work feature

Install & Run

# 1. Install (interactive wizard — run once)
npx github:ZKuroeSamaZ/work-board setup

# 2. Start the server
npx github:ZKuroeSamaZ/work-board start

Open http://localhost:7750

The setup wizard will:

1. Check prerequisites (Node, Docker, git, Claude CLI, Yarn)
2. Ask where to clone the repo
3. Configure PROJECTS_ROOT, terminal app, project aliases, and database
4. Install dependencies and run migrations

Config is saved to ~/.workboard/config.json so re-runs pre-fill your previous answers.

Other commands

npx github:ZKuroeSamaZ/work-board configure # update config only (no clone/migrate)

cmux users: The dev server must be started from inside a cmux workspace. See cmux setup below.

cmux Setup

cmux is a macOS terminal multiplexer. The Work Board backend communicates with it via a Unix socket to open new workspaces when you click Start Work.

Why it must run inside cmux

By default cmux uses socket mode cmuxOnly — only processes spawned inside a cmux workspace can write to the socket. The NestJS backend must inherit CMUX_WORKSPACE_ID from cmux to have permission.

Step-by-step

1. Install cmux from cmux.com and open the app.

2. Open a cmux workspace and navigate to the work-board directory:

   cd /path/to/work-board

3. Start the dev server from that workspace:

   yarn start

4. Click Start Work on any card — cmux opens a new workspace in the git project directory and runs:

   cmux claude-teams --continue    # resuming an existing session
   cmux claude-teams '<prompt>'    # first time — full task context passed to Claude

Alternative: Allow All socket mode

Go to cmux Settings → Socket Access Mode → Allow All. Then yarn start works from any terminal.

Using Other Terminals

Set TERMINAL_APP in backend/.env:

| Value | Behavior | |-------|----------| | cmux | Opens a new cmux workspace (recommended) | | wezterm | Opens a new WezTerm window | | iterm | Opens a new iTerm2 tab via AppleScript | | terminal | Opens a new Terminal.app window via AppleScript |

Environment Variables

All variables go in backend/.env. Run yarn configure to update interactively.

| Variable | Default | Description | |----------|---------|-------------| | DATABASE_URL | — | PostgreSQL connection string (required) | | PORT | 7749 | Backend HTTP + WebSocket port | | PROJECTS_ROOT | $HOME | Root directory scanned for git repos | | TERMINAL_APP | cmux | Terminal for Start Work (cmux, wezterm, iterm, terminal) | | PROJECT_ALIASES | {} | JSON map of shorthand → canonical repo name (e.g. {"sg":"singapore-backend"}) | | CLAUDE_PATH | auto | Override Claude CLI binary path | | DB_MAX_CONNECTION_POOL | 10 | Kysely pg pool max connections | | DB_IDLE_TIMEOUT_MS | 30000 | Pool idle timeout in ms | | DB_CONNECTION_TIMEOUT | 5000 | Pool connection timeout in ms | | LOG_QUERY | — | Set to true to log all SQL to stdout |

Project Aliases

Aliases let the AI resolve shorthand names to canonical git repo names in Smart Create. Fuzzy matching already handles similar names — only add aliases for abbreviations or names that share no characters with the repo.

PROJECT_ALIASES='{"sg":"singapore-backend","api":"my-api-service"}'

Scripts

| Command | Description | |---------|-------------| | yarn start | Kill ports 7749/7750, start backend (watch) + frontend (dev) | | yarn build | Production build for backend and frontend | | yarn setup | Install deps, generate Prisma client, run migrations | | yarn configure | Re-run config wizard from inside the install directory | | yarn migrate:dev | Create and apply a new Prisma migration | | yarn migrate:deploy | Apply pending migrations (production) | | yarn prisma:studio | Open Prisma Studio at http://localhost:5555 |

Database

PostgreSQL managed via Prisma v7 with multi-file schemas in backend/prisma/schemas/. Kysely handles all runtime queries — Prisma is used only for migrations and type generation.

Docker Compose

docker compose up -d   # starts postgres on port 5433
docker compose down    # stop
docker compose down -v # stop + wipe data

Schema changes

1. Edit backend/prisma/schemas/*.prisma
2. yarn migrate:dev — creates migration + regenerates Kysely types
3. Restart backend

Architecture

work-board/
├── bin/
│   └── create-work-board.mjs  npx setup wizard
├── backend/                   NestJS API
│   ├── src/
│   │   ├── kysely/            Kysely DB service (global module)
│   │   ├── works/             Work items CRUD, WebSocket gateway, Start Work
│   │   └── ai/                Claude-powered Smart Create / Suggest / Summary
│   └── prisma/
│       ├── schemas/           Prisma schema (multi-file)
│       ├── kysely/            Auto-generated Kysely types
│       └── migrations/        SQL migrations
└── frontend/                  Nuxt 3 app
    ├── pages/index.vue         Main board view
    ├── components/
    │   ├── ListView.vue        Table + card view with all actions
    │   └── ...
    └── composables/
        └── useWorks.ts         API + WebSocket state management

Start Work flow

1. User clicks Start Work on a card
2. Backend discovers git projects under PROJECTS_ROOT (depth 2)
3. Fuzzy-matches the card's gitProject to a discovered path (exact → case-insensitive → substring → bigram similarity ≥ 0.4)
4. First start: stores session marker, builds full-context Claude prompt
5. Resume: uses cmux claude-teams --continue to resume the last session in that directory
6. Opens cmux workspace (or other terminal) in the project directory
7. Sets card status to in-progress