Open source / Built for agent teams

Give every agent
a clear next task.

Name: agentic-kanban
Author: mrSamDev

Agentic Kanban — a lightweight coordination protocol for autonomous AI agents. No servers. No daemons. No queues. Durable task coordination through one SQLite file. Agents claim work atomically, report progress, survive crashes, and hand off reviews without anything in the middle.

Get started See the workflow

1Go binary
0services to run
15mrecoverable leases

terminal kanban init

# Scaffold the project
$ kanban init

→ .kanban/kanban.db
→ .kanban/agents/ (manager, worker, reviewer)
→ .kanban/skills/ (14 protocol skills)
→ .kanban/tools/ (kanban CLI)

14 skills · 3 agents · 1 binary

14 skills · 3 agents · 1 binary exit 0

01 / Install

One command. Nothing to host.

curl -sfL https://raw.githubusercontent.com/mrSamDev/agentic-kanban/main/install.sh | sh

Single Go binary + SQLite. For pinned versions, use GitHub Releases.

02 / Problem

One agent is fine.
Two agents need coordination.

One edits code. Another writes tests. A third reviews. Without shared state, they conflict, duplicate work, and wait.

Most setups reach for familiar infrastructure:

Agent frameworks
Message queues
Redis
Postgres
Background services
Complex orchestration layers

That's a lot to run for a handful of agents on the same machine.

The simpler answer

Treat coordination as a database problem.

Every agent reads and writes to the same SQLite file. No RPC. No event bus. No server process. Just durable shared state.

03 / Motivation

It started with a markdown file.

Sprint 1, task 1.1, task 1.2. Agents kept overwriting each other's updates, forgetting to mark things done, or picking up work already claimed. The file became noise fast.

The answer was a database. Every state change is a transaction, so two agents can't claim the same task. If one crashes, its lease expires and another picks it up — same as Rust's ownership model: one owner at a time, released when the owner disappears.

The .db file is the only coordination point. No server. No daemon. No message queue. Just a shared file on the filesystem you already share.

"The simplest coordination is the one you don't have to run."

04 / Why

Coordination that stays out of the way.

Use the filesystem you already share. Keep task ownership explicit and recoverable.

No server process

One .db file per project. No Redis, Postgres, queue, daemon, or network dependency.

Atomic claims

Concurrent agents calling claim-next receive different tasks through SQLite write serialization.

Crash recovery

Tasks use 15-minute leases. Progress renews ownership; expired work becomes claimable again.

Stable JSON

Commands write predictable JSON to stdout. Errors use stderr and exit code 2.

Bounded storage

Write-Ahead Log checkpointing prevents unbounded disk growth during long-running coordination.

Readable protocol

Markdown role skills teach agents the workflow without another tool-calling protocol.

05 / Workflow

A small protocol with clear ownership.

Three roles. Three plans. One lifecycle.

01
Plan
Manager reads spec → 3-pass extraction → user reviews proposal → approved tasks dispatch.
02
Claim
Worker claims highest-priority TODO (or reclaims expired leases). Dependencies respected.
03
Work
Heartbeats renew the 15-min lease. Blocked tasks get marked with reason.
04
Review
Complete directly or hand to reviewer. Reviewer approves or rejects with notes.

quick-start.sh

# Initialize with plan
$ kanban init --plan plan.md

# Manager: create plan proposal
$ kanban plan create plan.md
# User approves → kanban plan approve dispatches tasks

# Worker: claim next, work, complete
$ kanban task claim-next --agent alice --role worker
$ kanban task log-progress TASK-1 --agent alice --note "Done"
$ kanban task complete TASK-1 --agent alice --review

# Reviewer: review submission
$ kanban task approve TASK-1 --agent bob

01TODO

02IN_PROGRESS

03IN_REVIEW

04DONE

Plan flow: plan.md → proposal → approve → dispatch tasks

Rejection: IN_REVIEW → TODO (with reason)

Blocked: IN_PROGRESS → BLOCKED (lease cleared)

Crash recovery: lease expiry → lazy reclaim on next claim-next

Dependencies: tasks support depends_on — claim-next skips unmet deps by default

architecture

┌─────────────────────────────────────────────────────┐
│                 SQLite Database                      │
│              .kanban/kanban.db                       │
└─────────────┬───────────────┬────────────────────────┘
              │               │
 ┌────────────┴─────┐  ┌──────┴─────────────┐
 │   Agent Config   │  │    Embedded CLI     │
 │  agent .md files │  │  kanban task ...    │
 │  role definitions│  │  kanban skill ...   │
 └────────┬─────────┘  └──────────┬──────────┘
          │                       │
 ┌────────┴───────────────────────┴─────────┐
 │              Agent Roles                  │
 │  ┌──────────┐  ┌────────┐  ┌──────────┐ │
 │  │ manager  │  │ worker │  │ reviewer │ │
 │  │ .md file │  │ .md    │  │ .md      │ │
 │  │ plan     │  │ claim  │  │ approve  │ │
 │  │ dispatch │  │ work   │  │ reject   │ │
 │  └──────────┘  └────────┘  └──────────┘ │
 └──────────────────────────────────────────┘

No server. No daemon. No coordination service. One SQLite file, three roles.

06 / Reference

The complete command surface.

Small enough to learn, explicit enough to debug.

CommandRoleWhat it does

task dispatch --title --role [--project] [--priority] [--depends-on]any

Create a task with optional dependency list.

task claim <id> --agentworker, reviewer

Claim a specific task by ID (hierarchical delegation).

task claim-next --agent --role [--count N] [--project] [--respect-deps]worker, reviewer

Atomically claim the highest-priority task. --count N claims multiple.

task log-progress <id> --agent --note [--type]worker

Log progress and renew the 15-minute lease.

task extend-lease <id> --agent [--minutes]worker

Extend lease without logging progress (heartbeat).

task block <id> --agent --reasonworker

Mark blocked and clear the current lease.

task complete <id> --agent [--review]worker

Mark done or submit the task for review.

task view <id> [--notes] [--history]all

View task detail, notes, and history.

task search [--status] [--role] [--agent] [--project]manager

Filter the task list.

task approve <id> --agentreviewer

Move IN_REVIEW to DONE.

task reject <id> --agent --reasonreviewer

Return IN_REVIEW to TODO with context.

batch claim --agent --role [--count N] [--project]worker

Claim multiple tasks atomically.

batch complete --ids --agent [--to-review]worker

Complete multiple tasks in one transaction.

batch set-priority --ids --prioritymanager

Set priority for multiple tasks.

batch set-project --ids --projectmanager

Set a project label for multiple tasks.

task stats [--status] [--role]manager

Aggregate task statistics by status or role.

plan lintmanager

Check for structural problems (cycles, missing deps).

init [--harness generic] [--plan plan.md] [--dir]setup

Scaffold database, agent .md files, skill files.

re-initsetup

Re-scaffold agent files without touching the database.

events [--task TASK-1]all

View the event log, optionally filtered by task.

skill list / skill view <name>all

List or view embedded skill definitions.

07 / Skills

The agent runtime.

Skills teach agents the coordination protocol. Skills are embedded in the binary and scaffolded by kanban init.

How the roles use their skills

skill-flows

── manager/ ──

# "I need to turn a spec into tasks"
→ kanban plan create plan.md
# 3-pass extraction → writes proposal

# "The user approved the plan"
→ kanban plan approve
# dispatches all checked tasks

# "I need one task now"
→ kanban task dispatch --title "..." --role worker --priority 10

# "What's on the board?"
→ kanban task search --status BLOCKED
→ kanban task view TASK-4

# "Wire up Slack"
→ setup-hooks (bash)

── worker/ ──

# "I need work"
→ kanban task claim-next --agent alice --role worker
# grabs highest-priority TODO (or reclaims expired)

# "I know which task"
→ kanban task claim TASK-12 --agent alice

# "Making progress, renew my lease"
→ kanban task log-progress TASK-12 --agent alice --note "..."

# "I'm stuck"
→ kanban task block TASK-12 --agent alice --reason "..."

# "I'm done"
→ kanban task complete TASK-12 --agent alice --review

── reviewer/ ──

# "What needs reviewing?"
→ kanban task claim-next --agent bob --role reviewer

# "This looks good"
→ kanban task approve TASK-5 --agent bob
# status → DONE

# "Needs rework"
→ kanban task reject TASK-5 --agent bob --reason "..."
# status → TODO

Skill hierarchy

LayerContentsRole

Agent .md filesmanager.md · worker.md · reviewer.md

YAML frontmatter: tools, model, workflow steps

.kanban/skills/ (protocol)14 skill files + INDEX

Embedded in binary, teach coordination protocol

Agent Configagent .md files

Role definitions, workflow steps, tool references

kanban CLIgo binary

SQLite transactions, leases, WAL checkpointing

Protocol skills ship with the binary and teach coordination. Task skills teach domain logic — you bring your own. Both live side by side in .kanban/skills/.

Agent definition example: worker.md

.kanban/agents/worker.md

---
name: worker
description: Kanban worker agent that claims and completes tasks
---

You are a kanban worker agent. Claim and complete tasks
from the kanban board.

Workflow:
1. Claim the next available task
2. Work on the task, logging progress periodically
3. Submit for review or mark complete
4. If blocked, mark with reason

Long-running tasks:
For work >15 min, periodically run:
  kanban task extend-lease <task-id> --agent <name> --minutes 30

Use claim-next --count N to claim multiple tasks
for parallel execution.

Skills in .kanban/skills/ provide detailed usage
instructions for bash fallback.

How it works: init → agent run cycle

lifecycle

1. Scaffold
$ kanban init --plan plan.md
→ .kanban/kanban.db created
→ .kanban/agents/{manager,worker,reviewer}.md
→ .kanban/skills/ (14 skill files + INDEX)
→ plan.md parsed → tasks dispatched

2. Agent loads the config
$ kanban init
→ kanban CLI ready
→ 14 skills available

3. Run agents (harness-specific, e.g. pi run worker)
pi run manager
pi run worker
pi run reviewer
→ Agent reads its .md file
→ Uses CLI commands + skill docs

08 / Hooks

React to every event.

Drop an executable in .kanban/hooks/ and extend the workflow without touching the core.

EventExecutableWhen it fires

task.createdtask-created

Task dispatched

task.claimedtask-claimed

Agent claims a task

task.progresstask-progress

Progress logged

task.completedtask-completed

Task finished

task.submitted_for_reviewtask-submitted-for-review

Submitted for review

task.blockedtask-blocked

Blocked

review.approvedreview-approved

Approved

review.rejectedreview-rejected

Rejected

task.priority_updatedtask-priority-updated

Batch priority update

task.project_updatedtask-project-updated

Batch project label update

Hooks receive event JSON on stdin with a 30-second timeout. Errors log to stderr but don't fail the operation. Missing hooks are silently ignored. Chain multiple hooks using a .d/ directory — hooks run concurrently so a slow notifier won't block the caller.

.kanban/hooks/

task-created
task-completed
task-completed.d/
  slack
  metrics
  dashboard

09 / Fit

Built for local agent teams.

Not another agent framework.

Agentic Kanban solves one problem: reliable coordination. Bring your own agents, models, and workflow.

× Agent runtimes
× Tool calling
× Memory systems
× Planning engines
× Model hosting

Best for Claude Code subagents, Codex workflows, and local coding agents on the same machine or shared filesystem. Concurrency tested up to 50 agents.

Read the source

✓ Use it when

Agents need durable shared state
Task ownership must survive crashes
You want zero infrastructure overhead

× Skip it when

Agents run across untrusted networks
You need real-time push notifications
You have thousands of concurrent workers

Reference

Everything you need.

Install, configure, and extend agentic-kanban.

Git became the shared source of truth for code.
Agentic Kanban becomes the shared source of truth for work.

One database.
Every agent aligned.

Install agentic-kanban View on GitHub

Give every agenta clear next task.

One command. Nothing to host.

One agent is fine.Two agents need coordination.