Skip to content
Back to search

kanban-md

File-based kanban board for autonomous agentic loop. CLI and TUI for multi-agent workflows. Skills included.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/antopolskiy--kanban-md/badge.svg)](/listings/antopolskiy--kanban-md)

HTML

<a href="/listings/antopolskiy--kanban-md"><img src="/api/listings/antopolskiy--kanban-md/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

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](https://github.com/antopolskiy/kanban-md/releases/latest) page.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 1,089 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # kanban-md
  2. [![CI](https://github.com/antopolskiy/kanban-md/actions/workflows/build.yml/badge.svg)](https://github.com/antopolskiy/kanban-md/actions/workflows/build.yml)
  3. [![Release](https://github.com/antopolskiy/kanban-md/actions/workflows/release.yml/badge.svg)](https://github.com/antopolskiy/kanban-md/actions/workflows/release.yml)
  4. [![Go Version](https://img.shields.io/github/go-mod/go-version/antopolskiy/kanban-md)](https://go.dev/)
  5. [![Latest Release](https://img.shields.io/github/v/release/antopolskiy/kanban-md)](https://github.com/antopolskiy/kanban-md/releases/latest)
  6. [![codecov](https://codecov.io/gh/antopolskiy/kanban-md/graph/badge.svg)](https://codecov.io/gh/antopolskiy/kanban-md)
  7. [![Go Reference](https://pkg.go.dev/badge/github.com/antopolskiy/kanban-md.svg)](https://pkg.go.dev/github.com/antopolskiy/kanban-md)
  8. [![Go Report Card](https://goreportcard.com/badge/github.com/antopolskiy/kanban-md)](https://goreportcard.com/report/github.com/antopolskiy/kanban-md)
  9. [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
  10. An agent-first, file-based Kanban board for coordinating AI coding agents and
  11. human supervisors. It runs locally as a single binary: no database, server,
  12. account, or SaaS dependency.
  13. ![Demo](assets/demo.gif)
  14. ## How to use it
  15. `kanban-md` is flexible, but a typical agent-driven setup looks like this:
  16. 1. Install the tool.
  17. ```bash
  18. brew install antopolskiy/tap/kanban-md
  19. ```
  20. 2. Go to your project directory and create a board.
  21. ```bash
  22. kanban-md init
  23. ```
  24. This creates `kanban/config.yml` and `kanban/tasks/`. The interactive setup
  25. offers to add `kanban/` to `.gitignore`; keep it tracked instead if the board
  26. should travel with the repository.
  27. 3. Install the bundled skills for your agents.
  28. ```bash
  29. # Install skills locally in this project
  30. kanban-md skill install
  31. # Or install them globally
  32. kanban-md skill install --global
  33. ```
  34. 4. Create tasks manually, or ask an agent to capture them.
  35. ```bash
  36. kanban-md add "Set up CI pipeline" --priority high
  37. kanban-md add "Fix login bug" --priority critical
  38. claude "add ticket: there is a bug on the login page when the user enters an invalid email address"
  39. ```
  40. 5. Start the `kanban-based-development` skill with one agent. It will claim a
  41. task, create an isolated worktree, implement and verify the change, merge it,
  42. release the claim, and mark the task done. Once the workflow fits your
  43. project, run more agents and supervise their progress in the TUI.
  44. ```bash
  45. kanban-md tui
  46. ```
  47. 6. Adapt the local skill or `AGENTS.md` to the repository's own build, review,
  48. and release rules.
  49. ## Why kanban-md?
  50. Project management tools are designed for humans clicking buttons. kanban-md is designed for AI agents running commands and human supervision.
  51. - **Agent-first.** Token-efficient output (`--compact`), a single-step
  52. pick/claim/move workflow, structured JSON, and installable skills make the
  53. board practical inside non-interactive agent loops.
  54. - **Cooperative multi-agent coordination.** Claims reduce duplicate work, can be
  55. required by selected columns, and expire automatically when an agent stops
  56. renewing them. Claims are coordination leases, not a security or distributed-
  57. transaction boundary.
  58. - **Self-healing task IDs.** Commands automatically detect duplicate IDs, filename/frontmatter ID mismatches, and `next_id` drift, then repair them before proceeding.
  59. - **Plain files.** Every task is a Markdown file. Agents, humans, scripts, Git,
  60. and `grep` can inspect the same source of truth without API credentials.
  61. - **No service dependency.** A single binary owns the local workflow; there is
  62. no database server, background daemon, or remote configuration service.
  63. - **Skills included.** Pre-written skills for using the CLI tool and a multi-agent development workflow. Installable via `kanban-md skill install`.
  64. - **TUI for observation.** A full interactive terminal board with keyboard navigation. It auto-refreshes when task files change on disk.
  65. ```bash
  66. kanban-md tui
  67. ```
  68. ![Interactive TUI](assets/tui-demo.gif)
  69. ## Installation
  70. ### Homebrew (macOS/Linux)
  71. ```bash
  72. brew install antopolskiy/tap/kanban-md
  73. ```
  74. ### Go
  75. ```bash
  76. go install github.com/antopolskiy/kanban-md/cmd/kanban-md@latest
  77. ```
  78. Homebrew also installs `kbmd` as a shorthand alias for `kanban-md`.
  79. ### Binary downloads
  80. Pre-built binaries for macOS, Linux, and Windows are available on the [Releases](https://github.com/antopolskiy/kanban-md/releases/latest) page.
  81. ## Quick start
  82. Agents can run these commands for you, but the same interface is useful for
  83. manual work and scripting.
  84. ```bash
  85. # Initialize a board in the current directory
  86. kanban-md init --name "My Project"
  87. # Create some tasks
  88. kanban-md create "Set up CI pipeline" --priority high --tags devops
  89. kanban-md create "Write API docs" --assignee alice --due 2026-03-01
  90. kanban-md create "Fix login bug" --status todo --priority critical
  91. # List all tasks
  92. kanban-md list
  93. # Filter and sort, highest priority first
  94. kanban-md list --status todo,in-progress --sort priority
  95. # Move a task forward
  96. kanban-md move 3 in-progress
  97. kanban-md move 3 --next
  98. # Edit a task
  99. kanban-md edit 2 --add-tag documentation --body "Cover all REST endpoints"
  100. # View task details
  101. kanban-md show 1
  102. # Done with a task
  103. kanban-md move 1 done
  104. # Or soft-delete it by moving it to archived
  105. kanban-md delete 3 --yes
  106. ```
  107. ## How it works
  108. Running `kanban-md init` creates a `kanban/` directory:
  109. ```
  110. kanban/
  111. config.yml
  112. tasks/
  113. 001-set-up-ci-pipeline.md
  114. 002-write-api-docs.md
  115. 003-fix-login-bug.md
  116. ```
  117. Each task file is standard Markdown with YAML frontmatter:
  118. ```markdown
  119. ---
  120. id: 1
  121. title: Set up CI pipeline
  122. status: backlog
  123. priority: high
  124. created: 2026-02-07T10:30:00Z
  125. updated: 2026-02-07T10:30:00Z
  126. tags:
  127. - devops
  128. ---
  129. Optional body with more detail, context, or notes.
  130. ```
  131. When kanban-md updates a task, it retains unrecognized YAML frontmatter
  132. properties, including exact numeric text, tags, lists, and maps with non-string
  133. keys. Anchors, aliases, and nested YAML merges are retained when their bindings
  134. stay entirely within these properties. This lets other tools keep their metadata
  135. through task edits. By default, additional properties do not appear in table,
  136. compact, or JSON output. You can explicitly select scalar values for the
  137. [property views below](#selected-task-properties). kanban-md's own fields remain authoritative,
  138. including fields you clear.
  139. An update refuses before changing the task file if an extra property aliases a
  140. canonical field or another anchor that cannot be retained safely. Top-level YAML
  141. merges, top-level alias keys, and custom tags on the whole frontmatter mapping
  142. also require manual editing before an update. A quoted `"<<"` property is allowed.
  143. Otherwise valid tasks with this metadata remain readable. If startup needs to
  144. repair an inconsistent task ID or filename and cannot safely rewrite its
  145. metadata, the command fails with an error until you correct the task manually.
  146. kanban-md reserializes its own fields after an update. It does not guarantee
  147. comments, indentation, quote style, original key placement, or byte-for-byte
  148. formatting.
  149. The `config.yml` tracks board settings. A newly initialized board currently
  150. uses schema version 12:
  151. ```yaml
  152. version: 12
  153. board:
  154. name: My Project
  155. tasks_dir: tasks
  156. statuses:
  157. - name: backlog
  158. show_duration: false
  159. - name: todo
  160. - name: in-progress
  161. require_claim: true
  162. - name: review
  163. require_claim: true
  164. - name: done
  165. show_duration: false
  166. - name: archived
  167. show_duration: false
  168. priorities:
  169. - low
  170. - medium
  171. - high
  172. - critical
  173. defaults:
  174. status: backlog
  175. priority: medium
  176. class: standard
  177. claim_timeout: 1h
  178. classes:
  179. - name: expedite
  180. wip_limit: 1
  181. bypass_column_wip: true
  182. - name: fixed-date
  183. - name: standard
  184. - name: intangible
  185. tui:
  186. title_lines: 2
  187. age_thresholds:
  188. - after: 0s
  189. color: "242"
  190. - after: 1h
  191. color: "34"
  192. - after: 24h
  193. color: "226"
  194. - after: 72h
  195. color: "208"
  196. - after: 168h
  197. color: "196"
  198. next_id: 1
  199. ```
  200. `config.yml` and `tasks/*.md` are authoritative. `activity.jsonl` is a
  201. best-effort, bounded audit log, and `.lock` is a transient coordination file
  202. used by operations that must serialize access. Neither is a hidden database.
  203. Direct task-file edits remain supported, but commands are the claim-aware
  204. mutation path while a task is actively claimed.
  205. ## Commands
  206. ### `init`
  207. Create a new kanban board.
  208. ```bash
  209. kanban-md init [--name NAME] [--statuses s1,s2,s3] [--wip-limit status:N]
  210. ```
  211. | Flag | Description |
  212. |------|-------------|
  213. | `--name` | Board name (defaults to parent directory name) |
  214. | `--statuses` | Comma-separated status list (default: backlog,todo,in-progress,review,done,archived) |
  215. | `--wip-limit` | WIP limit per status (format: `status:N`, repeatable) |
  216. After creating a board interactively, kanban-md offers to add the board
  217. directory (for example, `kanban/`) to `.gitignore`:
  218. - If `.gitignore` exists in the board directory parent, the entry is appended.
  219. - If `.gitignore` does not exist, it is created with the board directory entry.
  220. ### `create`
  221. Create a new task. Aliases: `add`. Title can be provided as a positional argument or via `--title`.
  222. ```bash
  223. kanban-md create "My task" [FLAGS]
  224. kanban-md create --title "My task" --description "Details here" [FLAGS]
  225. ```
  226. | Flag | Default | Description |
  227. |------|---------|-------------|
  228. | `--title` | | Task title (alternative to positional argument) |
  229. | `--status` | config default | Initial status |
  230. | `--priority` | config default | Priority level |
  231. | `--assignee` | | Person assigned |
  232. | `--tags` | | Comma-separated tags |
  233. | `--due` | | Due date (YYYY-MM-DD) |
  234. | `--estimate` | | Time estimate (e.g. 4h, 2d) |
  235. | `--class` | config default | Configured class of service |
  236. | `--parent` | | Parent task ID |
  237. | `--depends-on` | | Dependency task IDs (comma-separated) |
  238. | `--body` | | Task description (alias: `--description`) |
  239. | `--set-property KEY=LITERAL` | | Set a scalar property; repeat for multiple keys |
  240. ### `list`
  241. List tasks with filtering and sorting. Aliases: `ls`.
  242. ```bash
  243. kanban-md list [FLAGS]
  244. ```
  245. | Flag | Default | Description |
  246. |------|---------|-------------|
  247. | `--status` | | Filter by status (comma-separated) |
  248. | `--priority` | | Filter by priority (comma-separated) |
  249. | `--assignee` | | Filter by assignee |
  250. | `--tag` | | Filter by tag |
  251. | `-s`, `--search` | | Search tasks by title, body, or tags (case-insensitive) |
  252. | `--blocked` | false | Show only blocked tasks |
  253. | `--not-blocked` | false | Show only non-blocked tasks |
  254. | `--parent` | | Filter by parent task ID |
  255. | `--unblocked` | false | Show only tasks with all dependencies satisfied (missing dependency IDs are treated as satisfied) |
  256. | `--unclaimed` | false | Show only unclaimed or expired-claim tasks |
  257. | `--claimed-by` | | Filter by claimant name |
  258. | `--class` | | Filter by class of service |
  259. | `--archived` | false | Show only archived tasks |
  260. | `--property KEY=LITERAL` | | Match one exact typed scalar value; repeat to combine with AND |
  261. | `--show-property KEY` | | Include a selected scalar in table, compact or JSON output; repeat for multiple keys |
  262. | `--group-by` | | Group counts by assignee, tag, class, priority, status, or `property:KEY` |
  263. | `--sort` | id | Sort by: id, title, status, priority, created, updated, due |
  264. | `-r`, `--reverse` | false | Reverse sort order |
  265. | `-n`, `--limit` | 0 | Max results (0 = unlimited) |
  266. ### `show`
  267. Show full details of a task. When the task has direct children, the detail view
  268. includes their IDs, statuses, titles, and a terminal/total roll-up. Parent
  269. status remains independently managed; the roll-up is informational only.
  270. ```bash
  271. kanban-md show ID
  272. kanban-md show ID --archived # include archived children in the roll-up
  273. ```
  274. | Flag | Description |
  275. |------|-------------|
  276. | `--archived` | Include archived direct children (hidden by default) |
  277. | `--show-property KEY` | Include a selected scalar on the task and its children; repeat for multiple keys |
  278. Children are ordered by task ID by default, matching `list --parent`.
  279. Set `children.detail_sort: property:reading_order` to use a numeric property
  280. instead. Finite numbers sort ascending, ties use task ID, and missing or
  281. unsuitable values follow in ID order. This changes detail views only, not list,
  282. board or pick order. See [selected task properties](#selected-task-properties).
  283. Human-readable CLI and TUI detail views prefix them with `├─` and `└─` tree
  284. guides so the parent-child relationship remains visually clear.
  285. Tasks with a direct parent show an upward relation such as
  286. `↑ Parent #1 [in-progress] Parent title`; if the parent file is unavailable,
  287. the relationship falls back to its stored task ID.
  288. JSON output always contains a `children` array; compact output adds a
  289. `children:DONE/TOTAL done` annotation only when children are present.
  290. **Parent links stay acyclic.** `create` and `edit` reject a parent that would
  291. close a ring, naming the chain it would form:
  292. ```
  293. $ kanban-md edit 2 --parent 1
  294. Error: parent would create a cycle (#2 → #1 → #2)
  295. ```
  296. `depends_on` is checked the same way, since two tasks that depend on each other
  297. can never become unblocked. Both checks run wherever the link is written, so
  298. `create --parent`, `edit --parent` and `edit --add-dep` are all covered.
  299. A representative board for trying the CLI and TUI behavior is available in
  300. [`examples/issue-11-demo`](examples/issue-11-demo/README.md).
  301. ### `edit`
  302. Modify an existing task.
  303. ```bash
  304. kanban-md edit ID [FLAGS]
  305. kanban-md edit 1,2,3 --priority high # batch edit
  306. ```
  307. | Flag | Description |
  308. |------|-------------|
  309. | `--title` | New title (renames the file) |
  310. | `--status` | New status |
  311. | `--priority` | New priority |
  312. | `--assignee` | New assignee |
  313. | `--add-tag` | Add tags (comma-separated) |
  314. | `--remove-tag` | Remove tags (comma-separated) |
  315. | `--due` | New due date (YYYY-MM-DD) |
  316. | `--clear-due` | Remove due date |
  317. | `--estimate` | New time estimate |
  318. | `--body` | New body text (replaces entire body) |
  319. | `--append-body`, `-a` | Append text to task body |
  320. | `--timestamp`, `-t` | Prefix a timestamp line when appending |
  321. | `--started` | Set started date (YYYY-MM-DD) |
  322. | `--clear-started` | Clear started timestamp |
  323. | `--completed` | Set completed date (YYYY-MM-DD) |
  324. | `--clear-completed` | Clear completed timestamp |
  325. | `--parent` | Set parent task ID |
  326. | `--clear-parent` | Clear parent |
  327. | `--add-dep` | Add dependency task IDs (comma-separated) |
  328. | `--remove-dep` | Remove dependency task IDs (comma-separated) |
  329. | `--block` | Mark task as blocked with reason |
  330. | `--unblock` | Clear blocked state |
  331. | `--claim` | Claim task for an agent (set claimed_by) |
  332. | `--release` | Release claim on task |
  333. | `--class` | Set class of service |
  334. | `--set-property KEY=LITERAL` | Set or replace a scalar property; repeat for multiple keys |
  335. | `--clear-property KEY` | Remove a property, distinct from setting it to null |
  336. ### `move`
  337. Change a task's status.
  338. ```bash
  339. kanban-md move ID [STATUS]
  340. kanban-md move ID --next
  341. kanban-md move ID --prev
  342. kanban-md move 1,2,3 todo # batch move
  343. ```
  344. | Flag | Description |
  345. |------|-------------|
  346. | `--next` | Advance to next status in the configured order |
  347. | `--prev` | Move back to previous status |
  348. | `--claim` | Claim task for an agent |
  349. ### `handoff`
  350. Hand off a task for review. Moves to `review` status, appends a note, and optionally blocks/releases.
  351. ```bash
  352. kanban-md handoff ID --claim NAME [--note TEXT] [--block REASON] [-t] [--release]
  353. ```
  354. | Flag | Description |
  355. |------|-------------|
  356. | `--claim` | Claim name (required) |
  357. | `--note` | Handoff note to append to body |
  358. | `--timestamp`, `-t` | Prefix a timestamp line to the note |
  359. | `--block` | Mark task as blocked with reason |
  360. | `--release` | Release claim after handoff |
  361. ### `delete`
  362. Soft-delete a task by moving it to `archived`. Aliases: `rm`.
  363. ```bash
  364. kanban-md delete ID [--yes]
  365. kanban-md delete 1,2,3 --yes # batch delete
  366. ```
  367. Prompts for confirmation in interactive terminals. Use `--yes` (`-y`) to skip
  368. the prompt; it is required in non-interactive contexts and for batch deletion.
  369. The task file remains on disk and can still be listed with `--archived`.
  370. ### `archive`
  371. Move a task explicitly to the `archived` status without a confirmation prompt.
  372. Archived tasks are hidden from normal commands (`list`, `board`, `metrics`,
  373. `context`, TUI) but remain on disk. Use `--claim` when archiving a task with an
  374. active claim.
  375. ```bash
  376. kanban-md archive ID
  377. kanban-md archive ID --claim agent-1 # archive a task claimed by agent-1
  378. kanban-md archive 1,2,3 # batch archive
  379. ```
  380. To see archived tasks:
  381. ```bash
  382. kanban-md list --archived
  383. kanban-md list --status archived
  384. ```
  385. ### `board`
  386. Show a board summary with task counts per status, WIP utilization, blocked/overdue counts, and priority distribution. Aliases: `summary`.
  387. ```bash
  388. kanban-md board
  389. kanban-md board --watch # live-update on file changes
  390. ```
  391. | Flag | Default | Description |
  392. |------|---------|-------------|
  393. | `-w`, `--watch` | false | Live-update the board on file changes (Ctrl+C to stop) |
  394. | `--group-by` | | Group counts by assignee, tag, class, priority, status, or `property:KEY` |
  395. ### `pick`
  396. Find and claim the next available task in one operation. Designed for
  397. cooperative multi-agent workflows where ownership needs to be visible.
  398. ```bash
  399. kanban-md pick --claim agent-1
  400. kanban-md pick --claim agent-1 --status todo --move in-progress
  401. kanban-md pick --claim agent-1 --tags backend
  402. kanban-md pick --claim agent-1 --parent 42
  403. kanban-md pick --claim agent-1 --no-body
  404. ```
  405. | Flag | Default | Description |
  406. |------|---------|-------------|
  407. | `--claim` | (required) | Agent name to claim the task for |
  408. | `--status` | all non-terminal | One source status to pick from |
  409. | `--move` | | Also move picked task to this status |
  410. | `--tags` | | Only pick tasks matching at least one tag |
  411. | `--parent` | | Only pick tasks that are children of this parent task ID |
  412. | `--no-body` | false | Show only the pick confirmation line (skip full task details) |
  413. By default, `pick` prints the one-line confirmation and then the full task details (same as `show`, including body) so agents do not need a follow-up `show` command.
  414. The pick algorithm selects from unclaimed, unblocked tasks with satisfied dependencies, prioritizing by class of service (expedite > fixed-date > standard > intangible), then by priority within each class. Fixed-date tasks are further sorted by earliest due date.
  415. ### `agent-name`
  416. Generate a random two-word name for use with `--claim`. Uses the system dictionary when available, with a built-in word list as fallback.
  417. ```bash
  418. kanban-md agent-name
  419. # → quiet-storm
  420. kanban-md pick --claim $(kanban-md agent-name) --status todo --move in-progress
  421. ```
  422. ### `metrics`
  423. Show flow metrics: throughput, average lead/cycle time, flow efficiency, and aging work items.
  424. ```bash
  425. kanban-md metrics [--since YYYY-MM-DD]
  426. ```
  427. | Flag | Default | Description |
  428. |------|---------|-------------|
  429. | `--since` | | Only include tasks completed after this date |
  430. ### `log`
  431. Show the activity log of board mutations. Emitted actions include `create`,
  432. `edit`, `move`, `delete`, `block`, `unblock`, `claim`, `release`, `handoff`, and
  433. TUI priority changes.
  434. ```bash
  435. kanban-md log [FLAGS]
  436. ```
  437. | Flag | Default | Description |
  438. |------|---------|-------------|
  439. | `--since` | | Show entries after this date (YYYY-MM-DD) |
  440. | `--limit` | 0 | Maximum number of entries (most recent) |
  441. | `--action` | | Filter by exact action name |
  442. | `--task` | | Filter by task ID |
  443. ### `config`
  444. View or modify board configuration.
  445. ```bash
  446. kanban-md config # show all config values
  447. kanban-md config get KEY # get a single value
  448. kanban-md config set KEY VALUE # set a writable value
  449. ```
  450. Available keys:
  451. | Key | Writable | Description |
  452. |-----|----------|-------------|
  453. | `board.name` | yes | Board name |
  454. | `board.description` | yes | Board description |
  455. | `defaults.status` | yes | Default status for new tasks |
  456. | `defaults.priority` | yes | Default priority for new tasks |
  457. | `defaults.class` | yes | Default class of service for new tasks |
  458. | `statuses` | no | List of statuses |
  459. | `priorities` | no | List of priorities |
  460. | `tasks_dir` | no | Tasks directory name |
  461. | `wip_limits` | no | WIP limits per status |
  462. | `claim_timeout` | yes | Claim expiration duration (e.g. `1h`, `30m`) |
  463. | `classes` | no | Class of service definitions |
  464. | `tui.title_lines` | yes | Number of title lines shown in TUI cards |
  465. | `tui.hide_empty_columns` | yes | Hide columns with zero tasks in TUI |
  466. | `tui.narrow_threshold` | yes | Terminal width below which the single-column view is used; 0 is automatic |
  467. | `tui.age_thresholds` | no | TUI age color thresholds |
  468. | `next_id` | no | Next task ID |
  469. | `version` | no | Config schema version |
  470. ### `context`
  471. Generate a markdown summary of the board state for embedding in context files (e.g. `CLAUDE.md`, `AGENTS.md`).
  472. ```bash
  473. kanban-md context # print to stdout
  474. kanban-md context --write-to AGENTS.md # write/update in file
  475. kanban-md context --sections blocked,overdue # limit sections
  476. kanban-md context --days 14 # recently completed lookback
  477. ```
  478. | Flag | Default | Description |
  479. |------|---------|-------------|
  480. | `--write-to` | | Write context to file (creates or updates in-place) |
  481. | `--sections` | all | Comma-separated section filter |
  482. | `--days` | 7 | Recently completed lookback in days |
  483. Available section names: `in-progress`, `blocked`, `overdue`, `recently-completed`.
  484. When using `--write-to`, the context block is wrapped in HTML comment markers (`<!-- BEGIN kanban-md context -->` / `<!-- END kanban-md context -->`). If the file already contains these markers, only the block between them is replaced — all other content is preserved.
  485. ## Interactive TUI
  486. `kanban-md tui` opens a full interactive terminal board with keyboard navigation. It auto-refreshes when task files change on disk.
  487. If no board exists in the current directory, `kanban-md tui` can initialize one and then offers to add that board directory to `.gitignore`.
  488. ```bash
  489. kanban-md tui # launch from any directory with a kanban/ board
  490. kanban-md tui --dir PATH # point to a specific kanban directory
  491. kanban-md tui --hide-empty-columns # override config and hide empty columns
  492. kanban-md tui --show-empty-columns # override config and show empty columns
  493. kanban-md tui --mouse # opt in to mouse navigation
  494. kanban-md tui --narrow # force the single-column layout at any width
  495. ```
  496. | Flag | Description |
  497. |------|-------------|
  498. | `--hide-empty-columns` | Hide empty columns for this run, overriding config |
  499. | `--show-empty-columns` | Show empty columns for this run, overriding config |
  500. | `--mouse` | Enable mouse navigation and drag-and-drop |
  501. | `--narrow` | Force the single-column layout at any terminal width |
  502. Set `tui.hide_empty_columns` in `config.yml` to control the default behavior.
  503. > **Note:** Older releases shipped a standalone `kanban-md-tui` binary. It has been retired — use `kanban-md tui` instead.
  504. In create/edit dialogs, text fields support cursor-based editing (`←/→`, `Home/End`, `Backspace`, `Delete`).
  505. Opening a task shows its known ancestor path and the same direct-child list and
  506. roll-up as `show`. Archived ancestors remain visible as context but cannot be
  507. opened; archived children remain hidden. Search and level filters control cards,
  508. not which active relations you can open in details.
  509. ### Explore task relations
  510. In details, `Tab` and `Shift+Tab` move the relation focus in reading order;
  511. `Enter` opens it. `Esc` or `Backspace` takes one step back, restoring your
  512. previous task, scroll position and relation focus. `q` closes the entire chain
  513. and returns to the board, keeping its search, level and sort settings. `j`/`k`,
  514. arrow keys and `g`/`G` still scroll the detail content.
  515. Ancestors appear root-first. On a milestone → epic → story path, the first
  516. `Tab` focuses the milestone; `Tab`, `Tab`, `Enter` opens the immediate epic.
  517. From that epic, `Tab`, `Enter` opens the milestone. Two `Esc` presses retrace
  518. those steps. Missing parent IDs and self/cycle markers remain visible rather
  519. than being repaired by navigation.
  520. ### Focus one hierarchy level
  521. In board mode, `v` cycles all tasks → the numeric levels present among active
  522. tasks → unknown depth, if present → all. Root tasks are `L0`, their children
  523. `L1`, and so on. Boards with hierarchy show these text labels beside task IDs
  524. and the active `level[...]` in the status line. Flat boards keep their usual
  525. cards by default. While typing a search, `v` is ordinary text.
  526. Levels come from parent links, including archived ancestors, and are not task
  527. types or stored fields. Missing/self-parent links use an effective level-zero
  528. root; a multi-task cycle and tasks reaching it have `L?`. The level filter and
  529. title/tag/ID search combine with AND. Neither writes task data.
  530. Task bodies are rendered as Markdown using the terminal's default foreground
  531. for the main text, so they remain readable when a terminal switches between
  532. light and dark themes while the TUI is running.
  533. ### Narrow mode (small terminals)
  534. On terminals too narrow to show every column side by side — a phone over SSH, a
  535. split pane — the board automatically switches to a single-column layout. It shows
  536. one column at a time, full width, under a two-line header: a tab strip of all
  537. columns (the active one highlighted) on top, and the active column's own full
  538. name, count, and WIP limit below. Card titles stay readable instead of being
  539. crushed to a few characters per column.
  540. Switch columns with `←`/`→`, `h`/`l`, or `Tab`/`Shift+Tab`. With `--mouse`, tap a
  541. tab to jump straight to that column; tapping a card selects it as usual.
  542. Narrow mode activates automatically once columns can no longer get a usable
  543. width. To force or tune it:
  544. ```bash
  545. kanban-md tui --narrow # force narrow mode for this run
  546. kanban-md config set tui.narrow_threshold 80 # persist a custom trigger width
  547. ```
  548. Set `tui.narrow_threshold` with `kanban-md config set` (or directly in
  549. `config.yml`) to override the automatic trigger — the board goes narrow below
  550. that terminal width. Use `0` for automatic behavior or `1` to effectively
  551. disable narrow mode.
  552. ### Mouse mode
  553. Mouse controls are opt-in, so the normal keyboard-only TUI remains unchanged.
  554. Start mouse mode with:
  555. ```bash
  556. kanban-md tui --mouse
  557. ```
  558. | Mouse action | Result |
  559. |--------------|--------|
  560. | Click a card | Select the card and synchronize keyboard navigation |
  561. | Double-click the same card within 500 ms | Open its detail view |
  562. | Click an active relation row in details | Open that task, including wrapped rows |
  563. | Click `Back` | Take one detail-history step, or return to the board when history is empty |
  564. | Wheel over a column | Activate that column and move its selection one card |
  565. | Wheel in a detail view | Scroll the task body three lines |
  566. | Hold a card, drag to another visible column, and release | Move the task to that status |
  567. The entire rendered destination column is a drop target, including its header,
  568. cards, and visible empty area. Releasing over the source column or outside a
  569. valid column cancels the drag. Keyboard shortcuts continue to work while mouse
  570. mode is active, so both input styles can be mixed freely.
  571. The board status line begins with the card count and `? help`, followed by the
  572. optional mouse indicator and the remaining actions. Shortcut characters are
  573. highlighted inside their action labels so the essential hints survive narrow
  574. terminal widths.
  575. Status moves made in the TUI preserve an existing task claim. If an unclaimed
  576. task enters a `require_claim` status, the TUI automatically claims it using the
  577. local hostname; that claim remains attached if the task later moves elsewhere.
  578. Terminals commonly reserve a modifier such as Shift or Option/Alt to bypass
  579. application mouse reporting for native text selection. The exact modifier is
  580. terminal-dependent; use the terminal's normal selection shortcut or omit
  581. `--mouse` when native selection is preferred.
  582. ### Keyboard shortcuts
  583. | Key | Action |
  584. |-----|--------|
  585. | `h` / `l` | Move between columns |
  586. | `j` / `k` | Move between tasks within a column |
  587. | `Enter` | View task details |
  588. | `c` | Create task in current column |
  589. | `e` | Edit selected task (same 4-step flow as create) |
  590. | `E` | Open the selected task's Markdown file in `$VISUAL`, then `$EDITOR`, then `vi` when available |
  591. | `m` | Move task to a different status (picker dialog) |
  592. | `n` / `p` | Move task to next / previous status |
  593. | `d` | Soft-delete (archive) task with confirmation |
  594. | `s` | Cycle the sort field (priority → created → updated → title) |
  595. | `S` | Reverse the sort direction |
  596. | `/` | Search/filter tasks live. Matches a case-insensitive substring of the title or any individual tag, not the body. Start with `#` for ticket IDs: `#12` prefix-matches IDs, `#12 ` exact-matches #12, and bare `#` matches all. `Enter` keeps the filter, `Esc` clears it |
  597. | `v` | In board mode, cycle exact hierarchy levels; session-only |
  598. | `Tab` / `Shift+Tab` in details | Focus relations in reading order |
  599. | `Enter` in details | Open the focused relation |
  600. | `Esc` / `Backspace` in details | Go back one navigation step |
  601. | `r` | Refresh board |
  602. | `?` | Show help |
  603. | `q` | Quit from the board; close the whole detail chain from details |
  604. | `Ctrl+C` | Quit |
  605. ## Global flags
  606. These work with any command:
  607. | Flag | Description |
  608. |------|-------------|
  609. | `--json` | Force JSON output |
  610. | `--table` | Force table output (default) |
  611. | `--compact` / `--oneline` | Compact one-line-per-record output |
  612. | `--dir` | Path to kanban directory (overrides auto-detection) |
  613. | `--no-color` | Disable color output (also respects `NO_COLOR` env var) |
  614. ### Output format
  615. The default output format is **table** (human-readable). Use flags to switch:
  616. ```bash
  617. # Default: table
  618. kanban-md list --status todo
  619. # Compact: one line per task, ideal for AI agents
  620. kanban-md list --compact
  621. # JSON: for scripting and piping
  622. kanban-md list --json | jq '.[].title'
  623. ```
  624. Set the `KANBAN_OUTPUT` environment variable to change the default: `json`, `table`, `compact`, or `oneline`.
  625. Override priority: `--json`/`--table`/`--compact` flags > `KANBAN_OUTPUT` env var > table default.
  626. ## Configuration
  627. kanban-md discovers its config by walking upward from the current directory, similar to how `git` finds `.git/`. This means you can run commands from any subdirectory in your project.
  628. Use `--dir` to point to a specific board:
  629. ```bash
  630. kanban-md --dir /path/to/kanban list
  631. ```
  632. ### Custom statuses
  633. Define your own workflow columns:
  634. ```bash
  635. kanban-md init --statuses "open,in-progress,blocked,closed"
  636. ```
  637. The order matters — it defines the progression for `move --next` and `move --prev`, and the sort order for `list --sort status`.
  638. ### Custom priorities
  639. Edit `config.yml` directly to customize priorities:
  640. ```yaml
  641. priorities:
  642. - trivial
  643. - normal
  644. - urgent
  645. - showstopper
  646. defaults:
  647. priority: normal
  648. ```
  649. Priority order runs from lowest to highest. `list --sort priority` shows the
  650. highest configured priority first by default; use `--reverse` for lowest first.
  651. ### Selected task properties
  652. Use your own top-level scalar properties for categories, reading order or other
  653. workflow data, without adding a task type or rank to the core model:
  654. ```bash
  655. kanban-md create "Draft chapter" --parent 1 \
  656. --set-property kind=chapter --set-property reading_order=20
  657. kanban-md edit 2 --set-property reading_order=10
  658. kanban-md list --property kind=chapter --show-property reading_order
  659. kanban-md list --group-by property:kind
  660. kanban-md show 1 --json --show-property kind --show-property reading_order
  661. ```
  662. Repeat `--set-property`, `--clear-property`, `--property` and `--show-property`
  663. for different keys. Keys are case-sensitive literal names matching
  664. `[A-Za-z_][A-Za-z0-9_.-]*`; a dot is part of the key, not a nested path.
  665. Task-owned names such as `status`, `priority`, `parent`, `body` and `file` are
  666. reserved: use their existing flags. Duplicate keys and simultaneous set/clear
  667. of the same key are errors. Multi-task edits retain the normal per-task batch
  668. behavior, not an all-or-nothing transaction.
  669. CLI literals support a bare string, a JSON-quoted string, a decimal/scientific
  670. number, lowercase `true`/`false`, or `null`. Shell quotes protect the argument;
  671. inner JSON quotes choose a string instead of a number or boolean:
  672. ```bash
  673. kanban-md edit 2 --set-property reading_order=20 # number
  674. kanban-md edit 2 --set-property 'reading_order="20"' # string, not a numeric order
  675. kanban-md edit 2 --set-property 'note=""' # empty string
  676. kanban-md edit 2 --set-property note=null # present null
  677. kanban-md edit 2 --clear-property note # absent key
  678. ```
  679. The authoring grammar does not evaluate YAML tags, aliases, arrays or maps.
  680. Use strict JSON numeric spelling on the CLI: quote `01`, `+20`, `.5`, `0x10`
  681. or `1_000` if you mean text. Reading existing YAML numeric forms is exact,
  682. including large values and base-prefixed integers; numeric-looking strings
  683. remain strings. Property equality is typed and exact. Repeated filters and
  684. ordinary filters combine with AND. Missing and unsupported values never match,
  685. including a filter for null.
  686. Edit these optional view settings directly in `config.yml`:
  687. ```yaml
  688. group_orders:
  689. property:kind: [milestone, chapter, story, bug]
  690. display:
  691. compact_fields: [status, property:kind]
  692. tui:
  693. card_fields: [property:kind]
  694. children:
  695. detail_sort: property:reading_order
  696. ```
  697. Omit them to retain `[status/priority]` compact chips, the TUI priority badge
  698. and ID-ordered children. Compact/card fields accept one or two distinct choices
  699. from `status`, `priority`, `class` or `property:KEY`; empty and null lists are
  700. invalid. Omit the field to use its defaults. Restart an open TUI after changing
  701. these config settings; its refresh command reloads tasks, not view settings.
  702. Compact fields apply to `list`, `show` and `pick`; other command confirmations
  703. keep their existing format.
  704. Child detail sort accepts `id` or one numeric property selector. Config version
  705. 12 migration preserves the old effective defaults and does not rewrite tasks.
  706. Group order is a presentation preference, not an enum. Configured values appear
  707. first; other strings follow alphabetically, then numbers, booleans and null.
  708. Missing or unsupported values share the last `(unclassified)` group. Scalar
  709. group labels are quoted/typed to keep text `"20"` distinct from number `20`.
  710. For example, a typo such as `chapetr` remains visible in the grouped summary;
  711. correct it with `edit ID --set-property kind=chapter`. Grouped output contains
  712. counts, not task records, so it cannot be combined with `--show-property`.
  713. Only `list` and `show` accept `--show-property`. It adds selected columns/tokens
  714. to human output and a `properties` object to each JSON task or child record.
  715. Missing keys are omitted, explicit null is present as null, and unsupported
  716. values are omitted with a warning. Nested, alias, timestamp, binary,
  717. custom-tagged and non-finite values remain preserved but are not selected
  718. scalars. Unselected metadata never enters task JSON. Display and sort settings
  719. do not select JSON values; use `--show-property` explicitly.
  720. Human badges use `KEY=--` for missing, `KEY=?` for unsupported and `KEY=null`
  721. for null; strings are quoted. Control characters are escaped and long badge
  722. values are shortened. Details show the selected properties that explain the
  723. view; JSON keeps their complete supported values when explicitly requested.
  724. Child ordering never changes priority, pick, dependencies, claims or WIP.
  725. Zero, negative and fractional numbers are valid; sparse values such as 10, 20,
  726. 30 leave room for inserts. Reparenting or clearing a parent retains the property.
  727. To reset placement when detaching, clear both in one edit:
  728. ```bash
  729. kanban-md edit 2 --clear-parent --clear-property reading_order
  730. ```
  731. An explicit property replacement/removal can still refuse if it would leave
  732. another retained YAML alias unsafe. The error leaves the task file unchanged
  733. and asks for manual frontmatter editing; unrelated values are not rewritten
  734. to make the edit succeed.
  735. ## Shell completions
  736. Generate completions for your shell:
  737. ```bash
  738. # bash
  739. source <(kanban-md completion bash)
  740. # zsh
  741. kanban-md completion zsh > "${fpath[1]}/_kanban-md"
  742. # fish
  743. kanban-md completion fish | source
  744. # PowerShell
  745. kanban-md completion powershell | Out-String | Invoke-Expression
  746. ```
  747. ## Agent skills
  748. kanban-md ships with installable skills that teach AI agents how to use the board. Skills are auto-triggered prompt files that give agents command references, decision trees, and workflows — so they manage tasks correctly without you writing custom instructions.
  749. Two skills are included:
  750. | Skill | Description |
  751. |-------|-------------|
  752. | **kanban-md** | Command reference, decision trees, and workflows for managing tasks via CLI. Auto-triggered when an agent encounters task-related work. |
  753. | **kanban-based-development** | Full autonomous development workflow — multi-agent claim semantics, git worktrees for isolation, and a strict status lifecycle (in-progress → review → done). |
  754. ```bash
  755. # Install skills for all detected agents (Claude Code, Codex, Cursor, OpenClaw)
  756. kanban-md skill install
  757. # Check if installed skills are up to date
  758. kanban-md skill check
  759. # Update skills to match current CLI version
  760. kanban-md skill update
  761. # Preview one skill
  762. kanban-md skill show --skill kanban-md
  763. ```
  764. Skills are versioned to match the CLI. When you upgrade kanban-md, `skill check` tells you if your installed skills are outdated, and `skill update` brings them in sync.
  765. ## Multi-agent workflow
  766. kanban-md coordinates concurrent work by multiple agents and humans through
  767. cooperative claims and classes of service.
  768. ### Claims
  769. Claims are cooperative leases: an agent claims a task before working on it, and
  770. well-behaved agents exclude tasks with active claims from selection. Claims
  771. expire after the configured timeout (default: 1 hour). They reduce collisions,
  772. but they are not a security boundary or a transactional distributed lock.
  773. On Unix-like systems, kanban-md also makes actively claimed task files read-only. Commands from the current claimant temporarily unlock the file while updating it, then restore read-only permissions; releasing or expiring the claim makes the file writable again. This protects against accidental direct edits by another process running as the same user, but it is not a security boundary: that user can still change permissions, rename, or delete the file.
  774. Statuses with `require_claim: true` (default: `in-progress` and `review`) enforce that every `move` or `edit` includes `--claim <name>`. This prevents accidental anonymous moves in multi-agent environments.
  775. ```bash
  776. # Agent picks next available task
  777. kanban-md pick --claim agent-1 --move in-progress
  778. # Move to review (require_claim enforced — must include --claim)
  779. kanban-md move 5 review --claim agent-1
  780. # Agent finishes and releases
  781. kanban-md edit 5 --release
  782. kanban-md move 5 done
  783. # Another agent picks from a specific queue
  784. kanban-md pick --claim agent-2 --status todo --tags backend
  785. ```
  786. ### Classes of service
  787. Tasks can have a class of service that affects WIP limits and pick priority:
  788. | Class | Behavior |
  789. |-------|----------|
  790. | **expedite** | Bypasses column WIP limits. Has its own board-wide WIP limit (default: 1). Picked first. |
  791. | **fixed-date** | Picked by earliest due date within its priority tier. |
  792. | **standard** | Default class. Normal WIP and priority rules. |
  793. | **intangible** | Picked last. For background/maintenance work. |
  794. ```bash
  795. kanban-md create "Critical hotfix" --class expedite --priority critical
  796. kanban-md create "Q2 deadline feature" --class fixed-date --due 2026-06-30
  797. ```
  798. ### Swimlanes
  799. Group board or list views by any field to see work distribution:
  800. ```bash
  801. kanban-md board --group-by assignee # who is working on what
  802. kanban-md board --group-by class # class of service breakdown
  803. kanban-md list --group-by tag # work by tag
  804. kanban-md list --group-by priority # priority distribution
  805. ```
  806. ## Design principles
  807. kanban-md provides orthogonal, composable workflow primitives. Development is
  808. one use, not the definition of its domain. These principles guide new features
  809. and reviews; they are not a claim that every existing implementation meets them.
  810. 1. Compose workflows; make new domain concepts earn their place. Prefer shared
  811. capabilities over built-in concepts named after one workflow.
  812. 2. Choose the smallest capability that actually solves the need. Count user
  813. effort and maintenance cost; a generic framework is not automatically simpler.
  814. 3. Keep the basic board complete; make workflow policy optional. Extras should
  815. impose no required setup or default clutter. Usability and data protection
  816. still deserve sensible defaults.
  817. 4. Give each value and action one explicit meaning. Separate task data, relations,
  818. views, and policy. Display order must not silently become execution order.
  819. 5. Keep local files authoritative and the core independently useful. Optional
  820. integrations must not make ordinary board use depend on accounts or services.
  821. 6. Preserve contracts across interfaces, upgrades, and writers. Keep mutations
  822. consistent, agent commands non-interactive, and existing boards compatible.
  823. The project-local [principal-owner skill](.agents/skills/kanban-md-principal-owner/SKILL.md)
  824. contains the review criteria, tradeoffs, and decision format. It is contributor
  825. guidance, not one of the workflow skills installed into users' projects.
  826. ## Development
  827. ```bash
  828. # Build
  829. make build
  830. # Run all tests (unit + e2e)
  831. make test
  832. # Run only e2e tests
  833. make test-e2e
  834. # Lint
  835. make lint
  836. # Lint with autofix
  837. make lint-fix
  838. # Full pipeline
  839. make all
  840. ```
  841. ## License
  842. [MIT](LICENSE)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.