Kanbaroo
A kanban-style issue tracker with a TUI, REST + WebSocket API, CLI, and MCP server. Designed to be useful standalone, and to integrate with trusty-cage for AI-driven workflows.
Status: Phase 2 complete. Single-user, terminal + web + AI.
What it does
Kanbaroo exposes the same data through five surfaces:
- TUI (Textual) for terminal-centric humans: workspace list, kanban board, story detail, fuzzy search, audit feed.
- Web UI (React SPA, served by the API at
/ui): workspace list, kanban board with drag-to-transition, epic list with open-story counts, story detail, comments, tags, live WebSocket updates, keyboard shortcuts. - CLI (Typer + Rich): scriptable access to every resource, JSON output for pipelines.
- REST + WebSocket API (FastAPI): the source of truth. WebSocket feeds live change events; REST is always authoritative.
- MCP server: lets AI agents (outer Claude in particular) read and write the board through the Model Context Protocol.
The data model is intentionally Jira-shaped but simpler. Workspaces contain optional Epics which contain Stories. Stories carry comments, tags, typed linkages, priority, and a standard kanban lifecycle. Every mutation is attributed to a human, claude, or system actor and recorded in an immutable audit log.
Architecture
flowchart TB
subgraph clients["Clients"]
TUI["TUI<br/>(Textual)"]
CLI["CLI<br/>(Typer + Rich)"]
MCP["MCP Server<br/>(mcp SDK)"]
WEB["Web UI<br/>(React SPA)"]
end
subgraph server["Kanbaroo Server"]
REST["FastAPI<br/>REST endpoints"]
WS["WebSocket<br/>event stream"]
CORE["kanbaroo-core<br/>(business logic)"]
end
subgraph storage["Storage"]
DB[("SQLite (local)<br/>Postgres (cloud)")]
end
subgraph external["External Consumers"]
DUCK["DuckDB / Snowflake<br/>(read-only)"]
GHA["GitHub Actions<br/>(read-only scripts)"]
end
TUI -->|HTTP + WS| REST
TUI -->|HTTP + WS| WS
CLI -->|HTTP| REST
MCP -->|HTTP| REST
WEB -->|HTTP + WS| REST
REST --> CORE
WS --> CORE
CORE --> DB
DB -.->|direct read| DUCK
DB -.->|direct read| GHA
style DUCK stroke-dasharray: 5 5
style GHA stroke-dasharray: 5 5
Installation
Requires Python 3.12 or newer.
# Everything (server + TUI + CLI + MCP)
pip install 'kanbaroo[all]'
# Or pick and choose:
pip install kanbaroo-api # Just the server (no web UI)
pip install 'kanbaroo-api[web]' # Server + bundled web UI at /ui
pip install kanbaroo-cli # CLI only (pulls in core)
pip install kanbaroo-tui # TUI only
pip install kanbaroo-mcp # MCP server only
Contributors working from a checkout should use the uv workspace instead:
uv sync --all-packages --dev
Quickstart
For a human walking up cold, all the way from install to a running board:
# 1. Install
pip install 'kanbaroo[all]'
# 2. Initialize config dir, apply migrations, mint your first token
kb init
# 3. Start the server (docker compose under the hood)
kb server start
# 4. Create your first workspace
kb workspace create --key KAN --name "My Work"
# 5. File a story
kb story create --workspace KAN --title "First task"
# 6. In another terminal, open the TUI on the board
kanbaroo-tui
Press ? on any TUI screen for the keybinding cheatsheet. Press / from the workspace list or board for fuzzy search. a opens the global audit feed.
Configuration
Kanbaroo reads settings from $KANBAROO_CONFIG_DIR/config.toml (default ~/.kanbaroo/config.toml), which kb init creates for you. Environment variables override the TOML values when set.
| Variable | Consumed by | Default / note |
|---|---|---|
KANBAROO_DATABASE_URL |
core, api, kb init, kb backup |
Required for the API to start. Docker supplies sqlite:////data/kanbaroo.db inside the container. |
KANBAROO_API_URL |
cli, tui, mcp | Overrides api_url in config.toml. Example: http://localhost:8080. |
KANBAROO_TOKEN |
cli, tui | Bearer token for API auth. Overrides token in config.toml. |
KANBAROO_MCP_TOKEN |
mcp | MCP-specific token; falls back to KANBAROO_TOKEN. |
KANBAROO_CONFIG_DIR |
cli, tui, mcp, kb init |
Override for the config directory. Default: ~/.kanbaroo. |
KANBAROO_WORKSPACE |
cli | Default workspace key so you can omit --workspace on every command. Example: KAN. |
KANBAROO_API_HOST |
api server | Uvicorn bind host. Default: 0.0.0.0. |
KANBAROO_API_PORT |
api server | Uvicorn bind port. Default: 8080. |
KANBAROO_COMPOSE_FILE |
kb server |
Path to a non-default docker-compose.yml (useful for CI). |
KANBAROO_MCP_LOG_LEVEL |
mcp | INFO by default; DEBUG for verbose MCP logs. |
For a long-lived single-user setup with per-project token attribution, host-bind-mounted SQLite, and nightly snapshots, see docs/deployment-dogfood.md. The fastest path to wire a single project up to a running Kanbaroo server is kb project init, which creates the workspace, mints a per-project claude token, and writes a project-root .mcp.json in one shot.
Web UI
The kanbaroo-web package ships a Vite + React SPA that kanbaroo-api serves at /ui. Once the API is running, visit http://localhost:8080/ui in a browser.
First-boot inside the container
kb server start runs docker compose up -d; the API runs inside the kanbaroo-api container with its SQLite DB in a host directory ($KANBAROO_DATA_DIR) bind-mounted at /data. That directory is empty on first boot, so migrations and the initial token have to happen inside the container:
# Bring the stack up
kb server start
# Apply migrations
docker compose exec -e KANBAROO_DATABASE_URL="sqlite:////data/kanbaroo.db" \
kanbaroo-api \
uv run --no-dev alembic -c /app/packages/kanbaroo-core/alembic.ini upgrade head
# Mint the first token (print it once; save it)
docker compose exec -e KANBAROO_DATABASE_URL="sqlite:////data/kanbaroo.db" \
kanbaroo-api \
uv run --no-dev kb init
Copy the kbr_ token that kb init prints and paste it into the /ui login form. The token is stored in browser localStorage under kanbaroo.token; press "Log out" to clear it.
You can also mint additional tokens later with kb token create --actor-type human --actor-id you --name "web" (inside the container, same docker compose exec wrapper).
Shipped in v0.2.0:
- Workspace list with inline create.
- Kanban board with drag-to-transition, illegal-move rejection, optimistic updates.
- Story detail: markdown description, metadata, comments (with one-level replies), tags, audit trail.
- Live updates via the existing
/api/v1/eventsWebSocket. - Story creation modal (
non the board). - In-board search (
/on the board; matches on human id prefix and title substring). - Keyboard shortcuts:
nnew story,/search,Eepic list,eedit story,?shortcut help,Escapeclose modal / clear search / exit edit mode.
Added after v0.2.0:
- Epics page (
/ui/workspaces/<id>/epics, orEon the board): key, title, state, story count, open count, last updated. Open means any state other than Done.
The release wheel auto-includes the built bundle, so pipx install --include-deps 'kanbaroo[all]' picks up the UI. Node 20+ is only required at build time for maintainers publishing a new release.
Developing the web UI
make web-build # Build the SPA into packages/kanbaroo-web/src/kanbaroo_web/dist/
make web-dev # Vite dev server on :5173, proxies /api and /api/v1/events to :8080
make web-test # vitest, single-shot
Upgrading
A Kanbaroo install has two halves that upgrade separately:
| Half | What it includes | How it upgrades |
|---|---|---|
| Clients | kb, kanbaroo-tui, kanbaroo-mcp (installed with pipx or pip) |
Reinstall the new version from PyPI |
| Server | The kanbaroo-api container, including the web UI at /ui |
Rebuild the Docker image from a checkout of the new version |
Upgrading the pipx install does not upgrade the server container, and the reverse is also true. The web UI is part of the server, so it changes only when you rebuild the container.
1. Read the changelog
Check CHANGELOG.md for every version between yours and the new one. Any release that adds a database migration says so there. A major version bump (for example 0.x to 1.0) can include breaking API or schema changes; minor and patch releases stay backwards compatible.
To see the version you have now:
pipx runpip kanbaroo list | grep kanbaroo
2. Back up the database
Stop the server and copy the SQLite file before changing anything on the server side:
kb server stop
mkdir -p "$HOME/.kanbaroo/backups"
cp "$KANBAROO_DATA_DIR/kanbaroo.db" "$HOME/.kanbaroo/backups/kanbaroo-pre-upgrade.db"
If you have not exported $KANBAROO_DATA_DIR, use the platform default listed in docs/deployment-dogfood.md. The restore steps are in that doc too.
3. Upgrade the server
The container is built from the source in your checkout, so move the checkout to the new release first, then rebuild:
cd /path/to/kanbaroo
git fetch --tags
git checkout v<new version>
docker compose up -d --build
kb server start runs docker compose up -d without --build, so it keeps using the old image. Use docker compose up -d --build (with $KANBAROO_DATA_DIR exported) whenever the source has changed. Your database is untouched by the rebuild because it lives on the host bind-mount.
4. Apply migrations
The API does not migrate the database on its own. After every server upgrade, run:
docker compose exec -e KANBAROO_DATABASE_URL="sqlite:////data/kanbaroo.db" \
kanbaroo-api \
uv run --no-dev alembic -c /app/packages/kanbaroo-core/alembic.ini upgrade head
This is safe to run when nothing has changed: if the database is already at the latest revision, it does nothing. To see the current revision, replace upgrade head with current.
Do not use kb init for this. It also applies migrations, but it mints a new token each time and refuses to run when a config already exists.
5. Upgrade the clients
pipx install --force --include-deps 'kanbaroo[all]==<new version>'
# Confirm every kanbaroo-* package landed on the new version
pipx runpip kanbaroo list | grep kanbaroo
You should see all seven packages (kanbaroo, -core, -api, -cli, -tui, -mcp, -web) at the new version. --include-deps is required; without it pipx hides the kb, kanbaroo-tui, and kanbaroo-mcp commands.
If you installed with plain pip instead, run pip install --upgrade 'kanbaroo[all]==<new version>' in the same environment.
Restart anything that keeps a client running, such as an open TUI or a Claude session using the MCP server, so it picks up the new code.
6. After the upgrade
- Reload any open
/uibrowser tabs so they load the new web bundle. Your saved login token still works. - The container's own
/root/.kanbaroo/config.tomlis reset by every image rebuild. This only matters if you runkbcommands inside the container; in that case re-runkb initthere. Host-side configs and tokens are unaffected. - Within a major version the REST API only gains endpoints, so older clients keep working against a newer server. A newer client may call an endpoint an older server does not have yet, so if you upgrade the two halves on different days, do the server first.
MCP setup
Let an AI agent drive Kanbaroo through the Model Context Protocol. The MCP server is a thin translator between the MCP tool protocol and the Kanbaroo REST API; every mutation routes through the API and is attributed to the MCP token's actor.
First create a dedicated claude-typed token so AI mutations are audited correctly:
kb token create --actor-type claude --actor-id outer-claude --name "claude"
Copy the plaintext that kb token create prints into KANBAROO_MCP_TOKEN in your shell, then add this to Claude's mcpServers block:
{
"mcpServers": {
"kanbaroo": {
"command": "kanbaroo-mcp",
"args": ["--api-url", "http://localhost:8080", "--token-env", "KANBAROO_MCP_TOKEN"]
}
}
}
See docs/mcp-setup.md for the full walkthrough, the smoke test, and the tool reference.
Docs
docs/spec.md: authoritative design intent. Start here if you want the why.docs/api-reference.md: generated REST API reference.docs/mcp-setup.md: MCP setup guide for AI agents.docs/future-skill-draft.md: draft workflow skill for AI agents using Kanbaroo via MCP.CLAUDE.md: guidance for Claude Code when working in this repo.CHANGELOG.md: release notes.
Development
This is a uv workspace monorepo with six packages in packages/ (kanbaroo-core, -api, -cli, -tui, -mcp, -web) and a top-level meta-package with an [all] extra. Before committing anything:
uv run ruff format .
uv run ruff check --fix .
uv run mypy packages/
uv run pytest
License
MIT. See LICENSE.
Metadata
Release files for kanbaroo 0.4.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| kanbaroo-0.4.0.tar.gz | 1.3 MB | Without provenance | Details for kanbaroo-0.4.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| kanbaroo-0.4.0-py3-none-any.whl | Python 3 | none | any | Details for kanbaroo-0.4.0-py3-none-any.whl |
Total release size: 1.3 MB
Release files / kanbaroo-0.4.0.tar.gz
| Download URL | kanbaroo-0.4.0.tar.gz |
|---|---|
| Size | 1.3 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
26766eb3b4e5926c3db38f97d5dcaf6abaaa991d6064e6986f9b945c0bfdee88
|
|
BLAKE2b-256 checksum How to use checksums |
f8f48a28eaa7977afe74303a09eb4e1da2ad8ebfc666a55b094e8e51cab4ad4f
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.11.7 {"installer":{"name":"uv","version":"0.11.7","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Release files / kanbaroo-0.4.0-py3-none-any.whl
| Download URL | kanbaroo-0.4.0-py3-none-any.whl |
|---|---|
| Size | 7.6 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
a5851204cc6756dc87f5091fe7864c47a8864eee8fcb24d8bb27fa0ab0b06e36
|
|
BLAKE2b-256 checksum How to use checksums |
d4bf1f8040cfee0b67f21d447c818ef97945e453a7b5a11374fba21c345cc959
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.11.7 {"installer":{"name":"uv","version":"0.11.7","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Security for kanbaroo 0.4.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.