Skip to main content

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/events WebSocket.
  • Story creation modal (n on the board).
  • In-board search (/ on the board; matches on human id prefix and title substring).
  • Keyboard shortcuts: n new story, / search, E epic list, e edit story, ? shortcut help, Escape close modal / clear search / exit edit mode.

Added after v0.2.0:

  • Epics page (/ui/workspaces/<id>/epics, or E on 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 /ui browser tabs so they load the new web bundle. Your saved login token still works.
  • The container's own /root/.kanbaroo/config.toml is reset by every image rebuild. This only matters if you run kb commands inside the container; in that case re-run kb init there. 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

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)

Source distribution for kanbaroo 0.4.0
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)

Table of built distributions (wheels) for kanbaroo 0.4.0
File Interpreter ABI Platform Actions
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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page