KanbAI

A file-based Kanban board that lives in your repo, built for Claude Code and other AI coding harnesses (and humans too). The board is plain Markdown files under .kanbai/, driven by a simple kanbai CLI and a local web UI. Installed and invoked as kanbai.

Why

• The board lives in your repo. One Markdown card per task, one folder per column — git-friendly, diffable, no external service, no database.
• Claude drives it. kanbai init installs a rule + skills so Claude picks the next task, implements it, and moves it across the board while you review.
• You stay in control. Finished work waits in review for your approval, and a friendly local web UI lets you watch and manage everything live.

How it works

kanbai init creates a .kanbai/ folder — one directory per column, one Markdown card per task:

.kanbai/
├── config.toml
├── backlog/
│   └── 004-add-oauth-login.md
├── todo/
├── doing/
├── review/
├── done/
└── archive/

Each card is Markdown with YAML frontmatter (managed by the CLI — don't edit by hand):

---
id: "004"
title: Add OAuth login
status: backlog
priority: high
order: 1
labels: [auth, backend]
deps: []
---

## Description
Support "Sign in with Google".

## Acceptance criteria
- [ ] OAuth flow works end to end

The sprint workflow

Cards flow through five columns:

kanbai next only reads the sprint (todo), respecting card order and blocking dependencies — so the backlog stays out of the way until you plan work into the sprint. When work is finished it goes to review; you approve it into done.

Install

uv add --dev kanbai          # add to your project as a dev dependency
# or
pip install kanbai

# for the web UI, install the extra:
uv add --dev 'kanbai[ui]'    # or: pip install 'kanbai[ui]'

Quick start

kanbai init                              # scaffold .kanbai/ + Claude integration
kanbai add "Build the login screen" -p high   # lands in the backlog
kanbai move 001 todo                     # plan it into the sprint
kanbai list                              # show the board

Then open a Claude Code session and ask it to "work through the KanbAI board".

Working with Claude Code

kanbai init installs the integration into .claude/:

• .claude/rules/kanbai.md — teaches Claude the board convention, loaded every session.
• Skills — kanbai-next (work one card and stop), kanbai-sprint (work the whole sprint), and kanbai-status (summarize the board).

Claude then works one card at a time:

1. kanbai next --json — pick the next actionable sprint task.
2. kanbai start <id> — move it to doing.
3. Implement it (reading kanbai show <id> --json for the details).
4. kanbai review <id> — send it to review and stop.
5. You review the work and approve it with kanbai done <id>.

Allow the CLI without prompts by adding Bash(kanbai *) to your .claude/settings.json.

Using another assistant (Cursor, Windsurf, Aider, Copilot, …)? The board is harness-agnostic — see docs/other-harnesses.md.

Web UI

kanbai ui                    # serves the board and opens your browser
kanbai ui --reload           # auto-restart on code changes (development)
kanbai ui --poll             # for sandboxes/containers without OS file events

The UI (FastAPI + HTMX, assets vendored so it works offline) lets you:

• View the board and create, edit, move, archive, or delete cards.
• Drag-and-drop between columns (with persisted reordering) or move from a card's modal.
• Plan a sprint (move several backlog cards to todo at once) and start a new sprint (archive done cards, optionally reset the active columns).
• Search cards and filter by label.
• Browse and restore archived cards.
• See WIP-limit and blocked-by-dependency indicators, and live updates as Claude moves cards from the CLI (via Server-Sent Events).

Configuration

.kanbai/config.toml is created by init and can be edited:

[board]
name = "my-project"
columns = ["backlog", "todo", "doing", "review", "done"]

[defaults]
priority = "medium"

# Optional work-in-progress limits per column (the CLI and UI warn when exceeded).
[wip]
doing = 3

Commands

Add --json to read-only commands for machine-readable output.

Changelog

See CHANGELOG.md.

License

MIT