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.

📖 Full documentation: www.r3ck.com.br/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]'

# for the AI command input (Anthropic and/or OpenAI), add the `ai` extra too:
uv add --dev 'kanbai[ui,ai]'    # or: pip install 'kanbai[ui,ai]'

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, on its own initiative, then stop.
5. You review it: approve and Claude runs kanbai done <id> (and commits) right away; ask for a change and it moves the card back to doing and repeats from step 3.

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).

AI command input

Type a natural-language instruction — "add a bug card about the login timeout" — and it pre-fills the "New card" form for you to review and confirm (it never creates the card directly). Works with Anthropic or OpenAI, whichever you have an API key for:

uv add --dev 'kanbai[ui,ai]'    # or: pip install 'kanbai[ui,ai]'
export ANTHROPIC_API_KEY=sk-ant-...     # or OPENAI_API_KEY=sk-...
kanbai ui                                # the input appears in the topbar

The input only appears when a key is set — no configuration required, and no error if you don't want to use it. Auto-detection order: ANTHROPIC_API_KEY first, then OPENAI_API_KEY (if both are set, Anthropic wins). Override with:

• KANBAI_AI_PROVIDER (anthropic or openai) — picks precedence between providers whose keys are already set; it does not work without that provider's own key present.
• KANBAI_AI_MODEL — a specific model ID, for either provider.

In the hub, the instruction can also name which board the card belongs to; in a single board's UI, the board is implicit.

Multi-board hub

Working across several projects? The hub serves all of them from one place, on a single port, with a board switcher — no more one server per project.

Since the hub spans projects, install KanbAI globally (or run it with uvx):

pipx install 'kanbai[ui]'
# or run without installing:
uvx --from 'kanbai[ui]' kanbai hub

Register your boards (each must already have a .kanbai/ — run kanbai init there), then start the hub:

kanbai hub add ~/projects/api        # register a board (named after its config.toml)
kanbai hub list                      # show registered boards
kanbai hub                           # serve them all; opens a landing to pick a board

Each board is served at /b/<name>/ and the registry lives in ~/.kanbai/boards.toml. Remove one with kanbai hub remove <name>. Hitting an unregistered or misspelled board URL shows a themed 404 page (with the registered boards as suggestions) instead of a bare JSON error.

Running the hub in the background

kanbai hub blocks the terminal it's run in. To keep the hub always available without tying up a terminal, run it as a background daemon instead:

kanbai hub start --port 8000   # start it, detached
kanbai hub status              # check whether it's running
kanbai hub logs -f             # follow its log
kanbai hub stop                # stop it

The daemon's PID and log file live under ~/.kanbai/ (hub.pid / hub.log), alongside the registry.

Configuration

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

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

# Skip the review stage: `kanbai review` finalizes cards straight to `done`, and the
# review column (if present) is hidden from the UI and the workflow skills.
# bypass_review = true

[defaults]
priority = "medium"

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

With bypass_review = true, there's no approval step — kanbai review <id> (and the Claude workflow skills) send a card straight to done, and the review column disappears from the web UI even if it's still present in columns.

Commands

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

Changelog

See CHANGELOG.md.

License

MIT