kanban

claude-kanban

A live kanban board that mirrors what Claude Code is doing in real time. Your todos, plan-mode plans, subagents and git commits move cards across Backlog → In progress → Review → Done. Open http://127.0.0.1:7331 in a browser next to your terminal and watch the cards travel while the agent works.

Zero runtime dependencies. One Node file for the server, one HTML file for the UI.

How it works

Claude Code ──hooks (HTTP)──▶  kanban-server.mjs  ──SSE──▶  browser (board)
                                  │
                                  └── state.json (per-project boards)

• Hooks POST raw event JSON straight to the local server (type: "http") — no shell scripts, no jq. A dead server never blocks your session because the HTTP hooks are fire-and-forget.
• Server — a single dependency-free Node file: holds state, serves the UI and streams changes to the browser over Server-Sent Events.
• UI — a single HTML file. FLIP animation slides cards smoothly between columns.

What moves the cards

The board is read-only: clicking a card opens its details (status, source, timing). Columns are driven exclusively by auto-sync — the source of truth is Claude's todos / plan / git history, never a manual drag.

Install

Requires Node 18+ on PATH. The auto-start launcher uses nohup/bash (Linux/macOS); on Windows run the server manually or use WSL.

From inside Claude Code:

/plugin marketplace add vasyakrg/claude-kanban
/plugin install kanban@kanban-dev

Then restart Claude Code so the hooks are picked up at session start.

Open the board: http://127.0.0.1:7331

git clone https://github.com/vasyakrg/claude-kanban.git
# inside Claude Code:
/plugin marketplace add /absolute/path/to/claude-kanban
/plugin install kanban@kanban-dev

Usage

• Just work as usual — cards appear the moment Claude starts tracking todos.
• For an existing project, run /kanban:init. Claude scans your plans, checklists and git history and seeds the board with starter cards at inferred statuses (read-only, it never edits your files).

Try it without Claude

You can drive the board by hand to see it move. Start the server and POST a few cards:

# start the server
node scripts/kanban-server.mjs

# health check
curl -fs http://127.0.0.1:7331/api/ping
# → {"ok":true,"port":7331}

# seed some cards (additive — never overwrites)
curl -s -X POST http://127.0.0.1:7331/api/seed \
  -H 'Content-Type: application/json' \
  -d '{"project":"demo","cards":[
        {"title":"Design the API","column":"done"},
        {"title":"Wire up SSE","column":"review"},
        {"title":"Build the board UI","column":"in_progress"},
        {"title":"Write the README","column":"backlog"}
      ]}'

Pick the demo project in the board header and the four cards appear. You can also simulate a real hook by POSTing a raw event to /hook:

curl -s -X POST http://127.0.0.1:7331/hook \
  -H 'Content-Type: application/json' \
  -d '{
        "hook_event_name":"PostToolUse",
        "tool_name":"TodoWrite",
        "cwd":"'"$PWD"'",
        "tool_input":{"todos":[
          {"content":"Refactor ingest()","status":"in_progress"},
          {"content":"Add tests","status":"pending"}
        ]}
      }'

Configuration

All settings are environment variables:

• Columns / status mapping: the COLUMNS and STATUS_TO_COLUMN constants in scripts/kanban-server.mjs.
• Run the server manually: node scripts/kanban-server.mjs.

HTTP API