Agent Kanban PM

Local-first Kanban project management for humans and headless CLI agents.

Status: release candidate (0.4.0rc8) for local, single-user development. The local runtime, board UI, per-task agent sessions, and MCP surface work and are covered by tests, including a database upgrade path. It is a single-operator tool by design: one shared token guards the local server, so do not expose it to an untrusted network or share an instance with people you would not give shell access.

The server stores state, starts assigned local agents, streams terminal output, and advances cards through the standard execution/review handoff. The selected orchestrator agent still owns planning, task splitting, assignment strategy, and escalation decisions. See ARCHITECTURE.md for the system diagram.

Requirements

• Python ≥ 3.11
• Linux or macOS. On Windows, use WSL; the local process runtime relies on Unix PTY/process semantics.
• git
• Recommended: tmux for detachable terminal sessions. If tmux is not available, the runtime uses its native PTY subprocess fallback.
• At least one CLI agent (Claude Code, Antigravity CLI, Codex, OpenCode, Aider, etc.)
• Optional: gh for GitHub PR/issue/review sync

Install

Release candidates need pre-release resolution:

pip install --pre agent-kanban-pm
kanban init

For an isolated CLI installation:

pipx install --pip-args="--pre" agent-kanban-pm
# Or run without installing:
uvx --prerelease allow --from agent-kanban-pm kanban --help

From source:

git clone https://github.com/Raman369AI/agent-kanban-pm.git
cd agent-kanban-pm
pip install -e ".[dev]"
kanban init

Run

kanban run                    # server + UI + role supervisor
kanban run --no-supervisor    # server + UI only

• UI: http://localhost:8000/ui/projects
• API docs: http://localhost:8000/docs

Board controls

Cards can be moved with drag-and-drop or entirely from the keyboard. Press Tab until a card is focused, then use Left Arrow or Right Arrow to move it to the adjacent stage. Task and approval dialogs keep focus inside the dialog, close with Escape, and return focus to the control that opened them.

The layout toggle (columns or a stacked list) and the density selector are remembered across reloads. Live board refreshes keep the focused card, its expanded tab, and column scroll positions, and wait until an in-flight drag or move has settled.

Server validation and authorization details are shown in the UI toast instead of being replaced by a generic “Failed” message. A rejected move is rolled back to its original column.

CLI

kanban roles list                                 # show role assignments
kanban roles assign worker opencode --mode headless # assign a role
kanban agents discover                            # find local CLIs
kanban sheet                                      # compact status
kanban audit                                      # what agents ran, and how
kanban audit --auto --commands                    # only unsupervised runs
kanban handoff status --workspace .               # inspect worktree state

Per-task execution

Each Kanban task that's assigned to an agent runs in its own background process session. tmux is used when available; otherwise the runtime falls back to a native PTY subprocess manager. Terminal output is captured into AgentActivity so the board workbench can show live progress without attaching to the shell.

For git projects, each task runs in an isolated worktree under ~/.kanban/worktrees/project-{id}/task-{id}-{agent} on a branch named kanban/task-{id}-{agent}. The branch is started from the project's detected base ref (origin/HEAD, then origin/main/origin/master, then a local main/master).

Before each session starts the launcher:

1. Fetches the base ref when an origin remote exists.
2. Rebases the task branch onto the base so parallel tasks don't drift from mainline.
3. Records the result (rebased onto ..., skipped (uncommitted changes), aborted (conflicts), etc.) as an AgentActivity you can audit from the board.

If the project directory is not a git worktree, the agent runs in the project folder directly with no git isolation.

Stage handoff

The default board stages are Backlog, To Do, In Progress, Review, and Done. The server does not choose which agent should do new work, but it does keep the standard role handoff moving once an assigned session finishes:

1. A worker assignment starts from To Do or In Progress.
2. When the agent marks STATUS.md with handoff_ready: true and state: done, completed, or review, the session streamer marks the session done and moves the card to Review.
3. Review-stage policy roles, normally test and diff_review, are assigned and launched from Review when configured in ~/.kanban/preferences.yaml.
4. When review/test sessions complete, the card moves to Done.
5. Done-stage policy roles, normally git_pr, may launch from Done to prepare PR or git contribution work.

Handoff follows each stage's workflow_key (backlog, to_do, in_progress, review, done), not its label, so stages can be renamed freely: a Done column relabelled "Shipped" still completes the tasks moved into it. The key is derived from the name when a stage is created and is kept when it is renamed; pass workflow_key when creating a custom stage to give it workflow meaning. Stages with no recognised key leave a moved task's status unchanged.

The handoff source of truth is each worktree's STATUS.md. If an agent exits without updating it, the card may stay where it is because the runtime cannot reliably tell whether the work is ready for review.

Bundled agent adapters

Each adapter is a YAML file describing how to launch one CLI. kanban init copies the bundled set into ~/.kanban/agents/, and you can drop your own file there without touching Python.

Gemini CLI is retired

Google shut Gemini CLI down for consumer accounts on 2026-06-18 and replaced it with Antigravity CLI (agy). The gemini adapter has been removed; if a role still names it, reassign that role:

kanban roles assign worker antigravity --mode headless

One behaviour worth knowing: agy --print writes nothing when its stdout is a pipe, so the orchestrator chat runs it on a pseudo-terminal (chat_designer.requires_tty: true in the adapter). Task sessions were already unaffected, since they run under tmux or a PTY.

Autonomy & approval

Agents run supervised by default: the CLI keeps its approval prompts, and risky actions (file writes, shell commands, git, network) surface in the Kanban approval queue for a human or the orchestrator.

Auto mode is an explicit per-role opt-in. Set autonomy: auto on a role in ~/.kanban/preferences.yaml (or answer y at the autonomy prompt in kanban init, or pass --autonomy auto to kanban roles assign). The launcher then appends the adapter's bypass flags — claude --permission-mode bypassPermissions, agy --dangerously-skip-permissions, codex --full-auto, opencode --auto, aider --yes-always, declared as task_command.auto_args in the adapter YAML — so the agent never pauses to ask. Combined with the per-task worktree, the blast radius is scoped to that worktree, and risky actions are expected to be recorded in STATUS.md. Critical review and approval records can still be created through the REST/MCP surfaces when an agent or human needs an explicit audit gate.

Auditing what agents did

Every agent start is written to an append-only activity log with the resolved command line, the workspace and branch, and the autonomy the session ran under. When an agent does something surprising, that record is what tells you what actually executed.

kanban audit                        # recent activity, oldest first
kanban audit --task 42              # one task's trail
kanban audit --auto                 # only sessions that ran with approvals off
kanban audit --commands             # only entries that recorded a command
kanban audit --since 24 --json      # last 24h, machine readable

kanban audit reads the database directly, so it still works when the server is not running. The same data is available over HTTP at GET /agents/activity (filters: agent_id, project_id, task_id, session_id, activity_type, has_command, limit), which requires the Kanban token like every other API route.

UI & token security

The server binds to loopback and authenticates every non-page request with a per-instance token (~/.kanban/token, owner-only 0600). Browser pages receive the token as an HttpOnly, SameSite=strict cookie; mutations authenticated by that cookie must also send the X-CSRF-Token header embedded in each page (wired automatically via a fetch wrapper in base.html). CLI and supervisor processes use the X-Kanban-Token header, which does not need the CSRF token. Requests with a non-loopback Host header are rejected before routing (DNS-rebinding defense); extend with KANBAN_ALLOWED_HOSTS if you deliberately serve a LAN hostname.

MCP Identity

CLI agents connect through agent_kanban_pm.mcp.server using local process identity:

KANBAN_AGENT_NAME=codex KANBAN_AGENT_ROLE=worker kanban-mcp

KANBAN_AGENT_NAME must match an adapter entity loaded from ~/.kanban/agents/.

Identity

• Humans: X-Entity-ID header
• Agents: KANBAN_AGENT_NAME env var
• Local-first, single-user. No auth server.

Roles and adapters

Adapters are YAML files in ~/.kanban/agents/. Adding a tool requires no Python changes. Role assignments live in ~/.kanban/preferences.yaml; the standard roles are orchestrator, ui, architecture, worker, test, diff_review, and git_pr.

Roles can also be edited from the board under Advanced → Team roles: each role, custom roles included, has its own agent, model, session mode, and approval setting, and saving one role leaves the others' unsaved edits alone. Options the editor does not show, such as owns or prompt_flag, are kept on save. The chosen model is passed to task and role sessions through the adapter's model_flag; default and <adapter>-default mean the CLI's own default, so no flag is sent.

Development

Install the regular development tools and run the fast checks:

pip install -e ".[dev]"
flake8 src tests
pytest
python -m build
twine check dist/*

Browser regressions are an optional extra. They start an isolated local server and cover drag-and-drop, keyboard movement, task editing, detailed error toasts, dialog focus, approval resolution, board layout preferences, renamed stages, and the role editor in Chromium:

pip install -e ".[dev,e2e]"
python -m playwright install chromium
pytest tests/e2e

Task creation and lifecycle updates shared by REST, browser UI, and MCP belong in agent_kanban_pm/services/tasks.py. Routers should retain only transport concerns such as authentication, response formatting, commits, and event publication. This keeps stage/parent validation and transition rules consistent across every interface.

Board behaviour and styling live in data/static/js/board.js, data/static/js/role-settings.js, and data/static/css/board.css; the kanban_board.html template holds markup only.

Package data is served from agent_kanban_pm/data/; the historical root-level agents/, mcp_configs/, static/, and templates/ folders are not part of the packaged runtime.

Roadmap

See PLAN.md for the full roadmap to a standalone, fully available release. Each phase is releasable on its own.

• Phase 0 — Stabilize (done): failing UI test fixed, CI installs the package and smoke-tests the built wheel, single-sourced dependencies, .env.example documents real env vars, dev-artifact name heuristics replaced with a Project.is_demo flag.
• Phase 1 — Packaging correctness: src/ layout, declared mcp dependency, install-safe data home.
• Phase 2 — Security hardening: /ui mutations require the token, HttpOnly cookie + CSRF header, Host-header validation, token file is 0600, supervised-by-default autonomy with explicit auto opt-in, WebSocket token verification.
• Phase 3 — Runtime correctness: async subprocess handling, atomic launch admission, MCP identity freshness, endpoint discovery, shutdown cleanup, and a shared task-mutation service have landed. Project, session, and approval services, MCP tool modularization, launcher decomposition, and Alembic migrations are still outstanding.
• Phase 4 — Product surface & docs: the support matrix, community scaffolding, browser workflow coverage, and extraction of the board's scripts and styles have landed. Landing-page visuals, the mkdocs site, coverage reporting, and extracting the remaining templates are still outstanding.
• Phase 5 — Release & distribution: 0.4.0rc8 is on PyPI and GitHub, published from a git tag by a workflow that authenticates through PyPI trusted publishing, with a weekly job that installs the released package to catch breakage. A stable 0.4.0 is what remains.

Security

See SECURITY.md for the supported threat model and private vulnerability reporting.

Contributing

See CONTRIBUTING.md. Release maintainers should also follow RELEASING.md.

License

MIT