bankan: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

What This Is

Ban Kan is a local AI agent orchestration dashboard — a Kanban board where tasks flow through Backlog → Planning → Implementation → Review → Done, with each stage driven by AI coding agents (Claude CLI or Codex CLI). Published as @stilero/bankan on npm.

Commands

npm run install:all        # Install root + server + client dependencies
npm run setup              # Interactive setup wizard (writes .env.local, installs deps)
npm run dev                # Run server + Vite client concurrently (alias: npm start)
npm run dev --prefix client   # Client only (Vite dev server on :5173)
npm run dev --prefix server   # Server only (node --watch on :3001)
npm run build              # Build client bundle (vite build)
npm run lint               # Run ESLint across the repo
npm run lint:fix           # Apply safe ESLint autofixes
npm test                   # Run server + client automated tests
npm run test:server        # Run server Vitest suite
npm run test:client        # Run client Vitest suite
npm run coverage           # Run both coverage suites and enforce the combined 80% gate

Dev mode: client runs at http://localhost:5173 with API proxy to :3001.

Architecture

Monorepo with two packages — no workspace manager, just npm --prefix:

• server/ — Express + WebSocket backend (ES modules, no TypeScript)
• client/ — React 18 + Vite SPA (JSX, no TypeScript, inline styles)
• bin/bankan.js — CLI entry point for npx @stilero/bankan
• scripts/setup.js — Interactive setup wizard

Server modules (server/src/)

• index.js — Express app, REST API, WebSocket handler, static file serving, bridge terminal logic. All HTTP/WS endpoints live here.
• orchestrator.js — Core pipeline engine. Poll loop (4s) assigns tasks to agents, signal checker (2.5s) detects completion/timeout/blockers. Builds prompts for each stage, manages git workspaces (clone → branch → push), handles PR creation via gh CLI.
• agents.js — Agent class wraps node-pty processes. AgentManager singleton manages agent pool with role-based scaling (planners/implementors/reviewers). Agents parse token counts from CLI output.
• store.js — TaskStore persists tasks to .data/tasks.json. Handles restart recovery (resets orphaned in-flight tasks).
• config.js — Loads settings from .data/config.json with fallback to .env.local and process env. Contains default prompts for planning/implementation/review stages.
• paths.js — Runtime path resolution. Two modes: development (.data/ in repo root) vs packaged (~/Library/Application Support/bankan on macOS).
• events.js — Shared EventEmitter bus connecting orchestrator, agents, store, and WebSocket broadcasts.