kanban-md

kanban-md

An agents-first file-based Kanban. Built for multi-agent workflows to allow AI agents work in parallel without clashing. Ultra-fast single binary CLI. Agent skills included. Lean and future-proof: no database, no server, no SaaS — just files.

How to use it

kanban-md is a flexible tool, and you can use it in many ways. Here is one of the ways I use it in my own projects:

1. Install the tool

brew install antopolskiy/tap/kanban-md

2. Go to your project directory and create a board there

kanban-md init

This will create a kanban/ directory and a config.yml file. I also usually add it to .gitignore.

3. Install skills for your agents

# install skills locally in this project -- I prefer this
kanban-md skill install 

# install skills globally (home directory)
kanban-md skill install --global

4. Create tickets manually, or ask your agents do it for you

kanban-md add "Set up CI pipeline" --priority high
kanban-md add "Fix login bug" --priority critical

claude "add ticket: there is a bug on the login page when the user enters an invalid email address"

5. Kick off /kanban-based-development skill in a single agent and observe how it behaves. It should claim a task, create a worktree, implement, test, commit, release the claim and mark the task as done. When confident, kick off the skill in multiple agents -- they will work in parallel without clashing. You should see the progress in the TUI.

kanban-md tui

6. Adjust the local skill / AGENTS.md to steer the agents in a way that would make sense for this project.

Why kanban-md?

Project management tools are designed for humans clicking buttons. kanban-md is designed for AI agents running commands and human supervision.

• Agents-first. Token-efficient output formats (--compact), atomic claim-and-move operations (pick --claim), and installable agent skills that teach agents how to use the board — out of the box.
• Multi-agent safe. Claims provide cooperative locking so multiple agents can work the same board without stepping on each other. Claims expire automatically, and the pick command atomically finds, claims, and moves the next available task.
• Self-healing task IDs. Commands automatically detect duplicate IDs, filename/frontmatter ID mismatches, and next_id drift, then repair them before proceeding.
• Plain files. Every task is a Markdown file. Agents, humans, scripts, and grep all work equally well. No API tokens, no authentication, no rate limits.
• Zero dependencies at runtime. A single static binary. No database, no server, no config service.
• Skills included. Pre-written skills for using the CLI tool and a multi-agent development workflow. Installable via kanban-md skill install.
• TUI for observation. A full interactive terminal board with keyboard navigation. It auto-refreshes when task files change on disk.

kanban-md tui

Installation

Homebrew (macOS/Linux)

brew install antopolskiy/tap/kanban-md

Go

go install github.com/antopolskiy/kanban-md/cmd/kanban-md@latest

Homebrew also installs kbmd as a shorthand alias for kanban-md.

Binary downloads

Pre-built binaries for macOS, Linux, and Windows are available on the Releases page.

Quick start

Note: normally, you wouldn't run the CLI commands directly. Your agents will do that for you.

# Initialize a board in the current directory
kanban-md init --name "My Project"

# Create some tasks
kanban-md create "Set up CI pipeline" --priority high --tags devops
kanban-md create "Write API docs" --assignee alice --due 2026-03-01
kanban-md create "Fix login bug" --status todo --priority critical

# List all tasks
kanban-md list

# Filter and sort, highest priority first
kanban-md list --status todo,in-progress --sort priority

# Move a task forward
kanban-md move 3 in-progress
kanban-md move 3 --next

# Edit a task
kanban-md edit 2 --add-tag documentation --body "Cover all REST endpoints"

# View task details
kanban-md show 1

# Done with a task
kanban-md move 1 done

# Or delete it
kanban-md delete 3 --yes

How it works

Running kanban-md init creates a kanban/ directory:

kanban/
  config.yml
  tasks/
    001-set-up-ci-pipeline.md
    002-write-api-docs.md
    003-fix-login-bug.md

Each task file is standard Markdown with YAML frontmatter:

---
id: 1
title: Set up CI pipeline
status: backlog
priority: high
created: 2026-02-07T10:30:00Z
updated: 2026-02-07T10:30:00Z
tags:
  - devops
---

Optional body with more detail, context, or notes.

The config.yml tracks board settings:

version: 3
board:
  name: My Project
tasks_dir: tasks
statuses:
  - backlog
  - todo
  - name: in-progress
    require_claim: true
  - name: review
    require_claim: true
  - done
  - archived
priorities:
  - low
  - medium
  - high
  - critical
wip_limits:
  in-progress: 3
  review: 2
classes:
  - name: expedite
    wip_limit: 1
    bypass_column_wip: true
  - name: fixed-date
  - name: standard
  - name: intangible
claim_timeout: 1h
defaults:
  status: backlog
  priority: medium
  class: standard
next_id: 4

Commands

init

Create a new kanban board.

kanban-md init [--name NAME] [--statuses s1,s2,s3] [--wip-limit status:N]

Flag	Description
--name	Board name (defaults to parent directory name)
--statuses	Comma-separated status list (default: backlog,todo,in-progress,review,done,archived)
--wip-limit	WIP limit per status (format: status:N, repeatable)

After creating a board, kanban-md prompts to add the board directory (for example, kanban/) to .gitignore:

• If .gitignore exists in the board directory parent, the entry is appended.
• If .gitignore does not exist, it is created with the board directory entry.

create

Create a new task. Aliases: add. Title can be provided as a positional argument or via --title.

kanban-md create "My task" [FLAGS]
kanban-md create --title "My task" --description "Details here" [FLAGS]

Flag	Default	Description
--title		Task title (alternative to positional argument)
--status	backlog	Initial status
--priority	medium	Priority level
--assignee		Person assigned
--tags		Comma-separated tags
--due		Due date (YYYY-MM-DD)
--estimate		Time estimate (e.g. 4h, 2d)
--class	standard	Class of service (expedite, fixed-date, standard, intangible)
--parent		Parent task ID
--depends-on		Dependency task IDs (comma-separated)
--body		Task description (alias: --description)

list

List tasks with filtering and sorting. Aliases: ls.

kanban-md list [FLAGS]

Flag	Default	Description
--status		Filter by status (comma-separated)
--priority		Filter by priority (comma-separated)
--assignee		Filter by assignee
--tag		Filter by tag
-s, --search		Search tasks by title, body, or tags (case-insensitive)
--blocked	false	Show only blocked tasks
--not-blocked	false	Show only non-blocked tasks
--parent		Filter by parent task ID
--unblocked	false	Show only tasks with all dependencies satisfied (missing dependency IDs are treated as satisfied)
--unclaimed	false	Show only unclaimed or expired-claim tasks
--claimed-by		Filter by claimant name
--class		Filter by class of service
--archived	false	Show only archived tasks
--group-by		Group results by field (assignee, tag, class, priority, status)
--sort	id	Sort by: id, title, status, priority, created, updated, due
-r, --reverse	false	Reverse sort order
-n, --limit	0	Max results (0 = unlimited)

show

Show full details of a task. When the task has direct children, the detail view includes their IDs, statuses, titles, and a terminal/total roll-up. Parent status remains independently managed; the roll-up is informational only.

kanban-md show ID
kanban-md show ID --archived  # include archived children in the roll-up

Flag	Description
--archived	Include archived direct children (hidden by default)

Children are ordered by task ID, matching the default list --parent order. Human-readable CLI and TUI detail views prefix them with ├─ and └─ tree guides so the parent-child relationship remains visually clear. Tasks with a direct parent show an upward relation such as ↑ Parent #1 [in-progress] Parent title; if the parent file is unavailable, the relationship falls back to its stored task ID. JSON output always contains a children array; compact output adds a children:DONE/TOTAL done annotation only when children are present.

Parent links stay acyclic. create and edit reject a parent that would close a ring, naming the chain it would form:

$ kanban-md edit 2 --parent 1
Error: parent would create a cycle (#2 → #1 → #2)

depends_on is checked the same way, since two tasks that depend on each other can never become unblocked. Both checks run wherever the link is written, so create --parent, edit --parent and edit --add-dep are all covered.

A representative board for trying the CLI and TUI behavior is available in examples/issue-11-demo.

edit

Modify an existing task.

kanban-md edit ID [FLAGS]
kanban-md edit 1,2,3 --priority high  # batch edit

Flag	Description
--title	New title (renames the file)
--status	New status
--priority	New priority
--assignee	New assignee
--add-tag	Add tags (comma-separated)
--remove-tag	Remove tags (comma-separated)
--due	New due date (YYYY-MM-DD)
--clear-due	Remove due date
--estimate	New time estimate
--body	New body text (replaces entire body)
--append-body, -a	Append text to task body
--timestamp, -t	Prefix a timestamp line when appending
--started	Set started date (YYYY-MM-DD)
--clear-started	Clear started timestamp
--completed	Set completed date (YYYY-MM-DD)
--clear-completed	Clear completed timestamp
--parent	Set parent task ID
--clear-parent	Clear parent
--add-dep	Add dependency task IDs (comma-separated)
--remove-dep	Remove dependency task IDs (comma-separated)
--block	Mark task as blocked with reason
--unblock	Clear blocked state
--claim	Claim task for an agent (set claimed_by)