kanbai

AI-powered kanban board with per-column agents for automated development workflows.

Features

• Per-column AI agents - Configure AI agents for each column with custom prompts, models, and triggers
• Git worktree isolation - Each agent runs in its own worktree for parallel, conflict-free work
• Multi-board support - Multiple boards per project with cross-board card movement
• Self-hosted - Run locally for solo work or deploy for team collaboration
• Dark minimal UI - Clean, distraction-free interface
• Flexible auth - Local mode, token-based, password, or OAuth (GitHub, GitLab, Bitbucket)

Installation

Quick start with npx (no install required)

cd /path/to/your/project
npx kanbai init
npx kanbai start

Global installation

Best for personal use across multiple projects:

npm install -g kanbai

# Then in any project:
kanbai init
kanbai start

Local installation (project dependency)

Best for teams who want version pinning:

npm install kanbai

Then add to your package.json scripts:

{
  "scripts": {
    "kanban": "kanbai start",
    "kanban:init": "kanbai init"
  }
}

Or run with npx:

npx kanbai start

Usage

Initialize a project

kanbai init

This creates a .kanban/ folder with:

• config.json - Global configuration
• users.json - User accounts (for token/password auth)
• boards/ - Board data and column configurations

Start the server

kanbai start

Options:

• -p, --port <port> - Port to run on (default: 3005)
• -d, --directory <dir> - Directory containing .kanban folder

Open your browser to http://127.0.0.1:3005

Manage boards

# List all boards
kanbai boards list

# Create a new board
kanbai boards create "My Board"
kanbai boards create "Sprint 1" --id sprint-1

Manage users

# List users
kanbai users list

# Add a user (returns auth token)
kanbai users add "Jane Doe" [email protected]

Configuration

Column agents

Each column can have an AI agent configured with:

• Role - Agent's purpose (e.g., "Code Reviewer", "Test Writer")
• Prompt - Instructions for the agent
• Model - AI model to use
• Trigger - When to run (manual, on-enter, on-update)
• Completion behavior - What happens when done (move to column, wait, conditional routing)

Authentication modes

Configure in .kanban/config.json:

{
  "auth": {
    "mode": "local"
  }
}

Modes:

• local - No auth, binds to 127.0.0.1 only
• token - API token authentication
• password - Username/password login
• oauth - OAuth with GitHub, GitLab, Bitbucket, etc.

How it works

1. Create cards - Add tasks to your board
2. Configure columns - Set up AI agents for columns like "In Progress", "Review", "Testing"
3. Move cards - When a card enters a column with an agent, the agent processes it
4. Agent isolation - Each agent runs in a git worktree (claude --worktree) for parallel work
5. Smart routing - Agents can pass/fail cards or route them to specific columns based on results

Requirements

• Node.js 18+
• Git (for worktree features)
• Claude CLI (for AI agents)

License

MIT