Metadata-Version: 2.5
Name: kanbai
Version: 0.7.0
Summary: A file-based Kanban board for Claude Code and other AI coding harnesses
Author-email: Rennan Cockles <rennan.cockles@experian.com>
License: MIT License
        
        Copyright (c) 2026 Rennan Cockles
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: agent,ai,claude,claude-code,kanban,task-management
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Environment :: Web Environment
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Requires-Dist: httpx2[socks]>=2.13
Requires-Dist: pydantic>=2.6
Requires-Dist: pyyaml>=6.0
Requires-Dist: rich>=13.0
Requires-Dist: tomli>=2.0; python_version < '3.11'
Requires-Dist: typer>=0.12
Provides-Extra: ai
Requires-Dist: anthropic>=0.69; extra == 'ai'
Requires-Dist: openai>=1.60; extra == 'ai'
Provides-Extra: build
Requires-Dist: uv>=0.7; extra == 'build'
Provides-Extra: ui
Requires-Dist: desktop-notifier>=6.0; extra == 'ui'
Requires-Dist: fastapi>=0.110; extra == 'ui'
Requires-Dist: jinja2>=3.1; extra == 'ui'
Requires-Dist: python-multipart>=0.0.9; extra == 'ui'
Requires-Dist: uvicorn[standard]>=0.29; extra == 'ui'
Requires-Dist: watchfiles>=0.21; extra == 'ui'
Description-Content-Type: text/markdown

<p align="center">
  <img src="https://raw.githubusercontent.com/rennancockles/kanbai/main/docs/assets/logo.png" alt="KanbAI" width="650">
</p>

# KanbAI

<p align="center">
  <a href="https://pypi.org/project/kanbai/"><img src="https://img.shields.io/pypi/v/kanbai?logo=pypi&logoColor=green&color=5865f9" alt="PyPI version"></a>
  <a href="https://pypi.org/project/kanbai/"><img src="https://img.shields.io/pypi/pyversions/kanbai" alt="Python versions"></a>
  <a href="https://github.com/rennancockles/kanbai/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/rennancockles/kanbai/ci.yml?branch=main&label=CI" alt="CI"></a>
  <a href="https://github.com/rennancockles/kanbai/blob/main/LICENSE"><img src="https://img.shields.io/github/license/rennancockles/kanbai" alt="License"></a>
  <a href="https://www.r3ck.com.br/kanbai/"><img src="https://img.shields.io/badge/docs-mkdocs--material-526cfe?logo=materialformkdocs&logoColor=white" alt="Documentation"></a>
</p>

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](https://www.r3ck.com.br/kanbai/)**

<p align="center">
  <img src="https://raw.githubusercontent.com/rennancockles/kanbai/main/docs/assets/board.png" alt="KanbAI web UI" width="840">
</p>

## 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):

```markdown
---
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:

| Column | Meaning |
|--------|---------|
| `backlog` | Everything to do eventually. New cards land here. |
| `todo` | The current sprint — what's planned for now. |
| `doing` | In progress. |
| `review` | Finished, awaiting your approval. |
| `done` | Approved and complete. |

`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

```bash
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

```bash
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](https://github.com/rennancockles/kanbai/blob/main/docs/other-harnesses.md).

## Web UI

```bash
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:

```bash
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`):

```bash
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:

```bash
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:

```bash
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:

```toml
[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

| Command | Description |
|---------|-------------|
| `kanbai --version` | Print the installed kanbai version. |
| `kanbai init` | Scaffold `.kanbai/` and install the Claude Code integration. |
| `kanbai add "title"` | Create a card in `backlog` (use `-c todo` for the sprint). |
| `kanbai list [column]` | Show the board, a single column, or the `archive`. |
| `kanbai next` | Print the next actionable card in the sprint (`todo`). |
| `kanbai show <id>` | Show full details of a card. |
| `kanbai move <id> <column>` | Move a card to a column. |
| `kanbai start <id>` | Move a card to `doing`. |
| `kanbai review <id>` / `kanbai done <id>` | Send a card to `review` / approve it to `done`. |
| `kanbai edit <id>` | Update fields of a card. |
| `kanbai archive <id>` / `kanbai restore <id>` | Archive a card / restore it from the archive. |
| `kanbai rm <id>` | Delete a card permanently. |
| `kanbai close-sprint` | Archive done cards (optionally reset active columns to the backlog). |
| `kanbai ui` | Serve the board in a local web UI (needs the `ui` extra). |
| `kanbai hub add/list/remove` | Manage the multi-board hub registry. |
| `kanbai hub` | Serve all registered boards on one port (needs the `ui` extra). |
| `kanbai hub start/stop/status` | Run the hub as a background daemon instead. |
| `kanbai hub logs [-f]` | Show (or follow) the hub daemon's log. |

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

## Changelog

See [CHANGELOG.md](https://github.com/rennancockles/kanbai/blob/main/CHANGELOG.md).

## License

MIT
