Kaban

Kanban for AI Agents
Track and coordinate tasks between humans and AI in the terminal

Features • Installation • MCP Integration • Hook • CLI • TUI • AI Editors

---

What is Kaban?

Kaban is a terminal-based Kanban board designed for AI code agents and developers. It provides a structured way to manage tasks, track progress, and coordinate between human users and AI agents.

Why Kaban?

• Manage Todos — Track tasks with a proper Kanban board
• Assign to Agents — Assign tasks to Claude, GPT, or any AI agent
• Single App — No servers, no cloud. One SQLite file. Works offline
• TUI + CLI + MCP — Interactive UI for humans, CLI for scripts, MCP for AI

Features

Feature	Description
MCP Server	AI agents can read, create, and manage tasks autonomously
TodoWrite Hook	Auto-sync Claude Code todos to Kaban board
Interactive TUI	Vim-style navigation, keyboard-driven workflow
Powerful CLI	Scriptable commands for automation
WIP Limits	Built-in Kanban best practices
Agent Tracking	See who (human or AI) owns each task
Portable	Single SQLite file, no server required

Installation

npx / bunx (Zero Install)

# Try without installing
npx @kaban-board/cli init --name "My Project"
npx @kaban-board/cli tui

# Or with bun
bunx @kaban-board/cli tui

npm (Global Install)

npm install -g @kaban-board/cli
kaban init --name "My Project"
kaban tui

Homebrew (macOS / Linux)

brew tap beshkenadze/tap
brew install kaban
kaban tui

From Source

git clone https://github.com/beshkenadze/kaban
cd kaban && bun install && bun run build
task install

Prerequisites

• Node.js v18+ or Bun v1.0+
• Task (optional, for development)

Packages

Kaban is a monorepo with three packages:

Package	Description
@kaban-board/core	Database logic, services, and schemas
@kaban-board/cli	CLI commands, TUI launcher, MCP server
@kaban-board/tui	Interactive Terminal User Interface

MCP Integration

Connect your AI coding assistant to Kaban via Model Context Protocol.

Claude Desktop Setup

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "kaban": {
      "command": "npx",
      "args": ["-y", "@kaban-board/cli", "mcp"],
      "env": {
        "KABAN_PATH": "/path/to/your/project"
      }
    }
  }
}

Or if installed globally:

{
  "mcpServers": {
    "kaban": {
      "command": "kaban",
      "args": ["mcp"],
      "env": {
        "KABAN_PATH": "/path/to/your/project"
      }
    }
  }
}

MCP Tools

Tool	Description
kaban_init	Initialize a new board
kaban_add_task	Add a task
kaban_add_task_checked	Add task with duplicate detection
kaban_get_task	Get task details
kaban_list_tasks	List tasks with filters
kaban_move_task	Move task to column
kaban_update_task	Update task properties
kaban_delete_task	Delete a task
kaban_complete_task	Mark task as done
kaban_status	Get board summary
kaban_archive_tasks	Archive completed/stale tasks
kaban_search_archive	Full-text search in archive
kaban_restore_task	Restore task from archive
kaban_purge_archive	Permanently delete archived tasks
kaban_archive_stats	Get archive statistics
kaban_reset_board	Delete ALL tasks (destructive)
kaban_add_dependency	Add task dependency
kaban_remove_dependency	Remove task dependency
kaban_check_dependencies	Check if dependencies resolved

MCP Resources

Resource	Description
kaban://board/status	Board status with counts
kaban://board/columns	Available columns
kaban://tasks/{columnId}	Tasks in a column
kaban://task/{id}	Single task details

CLI Usage

kaban <command> [options]

Commands

Command	Description
kaban init	Initialize a board
kaban add <title>	Add a task
kaban list	List tasks (with filters)
kaban move <id> [column]	Move a task (with optional --assign)
kaban assign <id> [agent]	Assign/unassign a task
kaban done <id>	Mark task complete
kaban status	Show board summary
kaban search <query>	Full-text search in archive
kaban archive	Archive completed tasks
kaban restore <id>	Restore task from archive
kaban purge	Permanently delete archived tasks
kaban reset	Delete ALL tasks (destructive)
kaban tui	Launch interactive UI
kaban mcp	Start MCP server
kaban hook install	Install TodoWrite sync hook
kaban hook status	Check hook status
kaban sync	Sync TodoWrite input (stdin)

Examples

# Initialize with custom name
kaban init --name "Sprint 1"

# Add task with metadata
kaban add "Fix auth bug" -c todo -a claude -D "OAuth2 flow broken"

# List tasks in a column
kaban list --column in-progress

# Move task to next column
kaban move abc123 --next

# Move and assign to agent in one command
kaban move abc123 in-progress --assign claude

# Assign task to an agent
kaban assign abc123 claude

# Unassign a task
kaban assign abc123 --clear

# Mark complete
kaban done abc123

Claude Code Hook Integration

Optional but recommended — Automatically sync Claude Code's TodoWrite with your Kaban board. You can still use Kaban without this hook via CLI, TUI, or MCP.

Installation

kaban hook install

This will:

1. Install the hook binary to ~/.claude/hooks/
2. Configure Claude Code's settings.json with a PostToolUse hook
3. Create a backup of your settings

Commands

Command	Description
kaban hook install	Install the TodoWrite sync hook
kaban hook uninstall	Remove the hook
kaban hook status	Check installation status and activity

How It Works

Claude Code → TodoWrite → Hook → kaban sync → Kaban Board

• pending todos → Todo column
• in_progress todos → In Progress column
• completed todos → Done column
• cancelled todos → Backlog column

Logs

Sync activity is logged to ~/.claude/hooks/sync.log. View recent activity:

kaban hook status

TUI Usage

Launch the interactive terminal UI:

kaban tui

Keyboard Shortcuts

Key	Action
< > / h l	Navigate columns
^ v / j k	Navigate tasks
Enter	View task details
a	Add new task
e	Edit task
m	Move task
u	Assign user/agent
d	Delete task
x	Archive task
r	Restore from archive
Tab	Toggle archive view
?	Show help
q	Quit

AI Code Editors

Add Kaban MCP server to your AI coding assistant:

Claude Code Skill (Recommended)

Install the Kaban workflow skill for TodoWrite sync and session persistence:

bunx skills add beshkenadze/kaban

Works with all AI code editors: Antigravity, Claude Code, Clawdbot, Cline, Codex, and 21+ more.

The skill includes:

• MCP server — Auto-configured, no manual setup needed
• Kaban workflow skill — Syncs with TodoWrite, resumes tasks across sessions
• Session hooks — Auto-checks for in-progress tasks on session start

Alternative: Plugin Marketplace

/plugin marketplace add beshkenadze/kaban
/plugin install kaban-workflow@beshkenadze-kaban

Claude Code / Claude Desktop (Manual MCP)

Add to .mcp.json (Claude Code) or claude_desktop_config.json:

{
  "mcpServers": {
    "kaban": {
      "command": "npx",
      "args": ["-y", "@kaban-board/cli", "mcp"]
    }
  }
}

OpenCode

Add to opencode.json:

{
  "mcp": {
    "kaban": {
      "command": "npx",
      "args": ["-y", "@kaban-board/cli", "mcp"]
    }
  }
}

Cursor / Windsurf / Continue

Add to MCP settings:

{
  "mcpServers": {
    "kaban": {
      "command": "npx",
      "args": ["-y", "@kaban-board/cli", "mcp"]
    }
  }
}

With Global Install

If you installed globally (npm i -g @kaban-board/cli), use:

{
  "mcpServers": {
    "kaban": {
      "command": "kaban",
      "args": ["mcp"]
    }
  }
}

Configuration

Environment Variables

Variable	Description	Default
KABAN_PATH	Board data directory	Current directory
KABAN_AGENT	Default agent name	user

Data Storage

Kaban stores data in .kaban/ directory:

.kaban/
├── board.db      # SQLite database
└── config.json   # Board configuration

Default Columns

Column	WIP Limit
Backlog	—
To Do	—
In Progress	3
Review	2
Done	— (terminal)

Contributing

Contributions are welcome! Please read our Contributing Guide first.

# Development
bun install
bun run build
bun run lint
bun run test

Commit Convention

We use Conventional Commits for automated releases:

feat: add new feature      # → Minor version bump
fix: resolve bug           # → Patch version bump  
feat!: breaking change     # → Major version bump

See CONTRIBUTING.md for full details on commit types and the release process.

License

MIT