agentic-kanban 0.1.1

Kanban board for managing AI agent sessions

Agentic Kanban

A kanban board for managing AI agent sessions.

Each ticket is bound to an agent session (Claude Code, pi.dev) running inside its own git worktree, executed in the target repository's existing devcontainer. The active harness is selected globally in the app's settings.

Install

python:

uv tool install agentic-kanban

This will install the binary to ~/.local/bin/kanban.

docker:

SOURCE=$HOME/code
docker run -d --name kanban \
  --restart unless-stopped \
  -p 127.0.0.1:7474:7474 \
  -p 13000-13099:13000-13099 \
  -v ${DOCKER_SOCK_PATH:-/var/run/docker.sock}:/var/run/docker.sock \
  -v $HOME/.claude:$HOME/.claude \
  -v $HOME/.local/share/kanban:$HOME/.local/share/kanban \
  -v $SOURCE:$SOURCE \
  -e HOME=$HOME \
  -e XDG_RUNTIME_DIR=$XDG_RUNTIME_DIR \
  -e KANBAN_DATA_DIR=$HOME/.local/share/kanban \
  -e GH_TOKEN=$(gh auth token) \
  lahmanja/kanban:latest

TIP: Set DOCKER_SOCK_PATH in your shell for rootless Docker support.

github:

Prebuilt packages are available from Github Releases.

Build

docker bake

Configuration

Kanban reads two TOML files and merges them, with user values overriding project values per key:

• Project: <repo>/.kanban.toml — checked into the target repo, applies to every worktree of that repo.
• User: $XDG_CONFIG_HOME/kanban/config.toml (falling back to ~/.config/kanban/config.toml) — your personal overrides across all repos.

Either file may be absent. Both accept the same schema:

[harness]
id = "claude-code"            # default harness for new sessions

[sync]
allow_rebase = true            # offer "rebase onto base" in the sync menu
allow_merge  = true            # offer "merge base into branch"

[merge]
allow_merge_commit = true      # which strategies appear in the merge menu
allow_squash       = true
allow_rebase       = false

[github]
auto_move     = true           # move tickets when the linked PR/issue changes state
draft_column  = "In Progress"
review_column = "In Review"
done_column   = "Done"
closed_column = "Done"

# Extra knobs layered onto the worktree's devcontainer.json at session spawn.
# `mounts` and `run_args` append to whatever the devcontainer.json declares;
# `container_env` merges with kanban values winning.
[devcontainer]
mounts   = ["type=bind,source=/tmp/ssh-agent.sock,target=/tmp/ssh-agent.sock"]
run_args = ["--cap-add=SYS_PTRACE"]

[devcontainer.container_env]
SSH_AUTH_SOCK = "/tmp/ssh-agent.sock"

# Per-task ports: associate .vscode/tasks.json labels with container ports.
# When such a task runs, kanban allocates a host port from 13000-13099 and
# runs a TCP proxy.
[[task]]
label = "Start Frontend"
container_port = 3000

[[task]]
label = "Start Backend"
container_port = 8080

[[task]] entries merge by label: a user entry with the same label replaces the project entry, and user-only labels are appended.

The user-config path can also be overridden from the CLI: kanban serve --config /path/to/config.toml (or $KANBAN_CONFIG) replaces the default $XDG_CONFIG_HOME/kanban/config.toml lookup.

API

The HTTP server (default :7474) exposes a small REST API. The endpoint most useful for scripting is ticket creation.

POST /api/boards/{id}/tickets

Path parameter {id} accepts either the numeric board id or the board slug.

Body fields:

Field	Type	Required	Notes
title	string	yes
body	string	no	Markdown ticket description.
column_id	integer	no	Numeric column id. Wins over column if both set.
column	string	no	Column name (case-insensitive) or numeric string. Defaults to the leftmost column when omitted.

Returns 201 with the created Ticket JSON, or 400 / 404 on validation failures. SSE subscribers on /api/boards/{id}/events receive a ticket_created event.

The server has no authentication — bind only to 127.0.0.1 (the default container mapping does this).

CLI

When kanban is installed natively (e.g. go install or a release binary on $PATH), two subcommands wrap the API for shell use:

# List boards
kanban list-boards

# Create a ticket (default column = leftmost)
kanban create-ticket --board my-board --title "Investigate flaky test"

# Pick a column, attach a body, get full JSON back
kanban create-ticket \
  --board my-board \
  --title "Wire CI" \
  --column "In Progress" \
  --body "add a workflow" \
  --json

Both commands take --server (default http://localhost:7474); the KANBAN_URL env var is used as a fallback.

MCP

The same binary can run as a Model Context Protocol server over stdio, exposing kanban tools to AI agents. The MCP server is a thin client of the HTTP API above, so kanban serve must be running.

kanban mcp --server http://localhost:7474
# or via env
KANBAN_URL=http://localhost:7474 kanban mcp

Tools:

• create_ticket — args: board (id or slug), title, optional body, optional column (name or id, defaults to leftmost column).
• list_boards — returns [{id, name, slug}] for discovery.

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "kanban": {
      "command": "/path/to/kanban",
      "args": ["mcp", "--server", "http://localhost:7474"]
    }
  }
}

Claude Code

claude mcp add kanban -- /path/to/kanban mcp --server http://localhost:7474