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.
Badge for your README
Markdown
[](/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
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)
- # kanban-md
- [](https://github.com/antopolskiy/kanban-md/actions/workflows/build.yml)
- [](https://github.com/antopolskiy/kanban-md/actions/workflows/release.yml)
- [](https://go.dev/)
- [](https://github.com/antopolskiy/kanban-md/releases/latest)
- [](https://codecov.io/gh/antopolskiy/kanban-md)
- [](https://pkg.go.dev/github.com/antopolskiy/kanban-md)
- [](https://goreportcard.com/report/github.com/antopolskiy/kanban-md)
- [](LICENSE)
- An agent-first, file-based Kanban board for coordinating AI coding agents and
- human supervisors. It runs locally as a single binary: no database, server,
- account, or SaaS dependency.
- 
- ## How to use it
- `kanban-md` is flexible, but a typical agent-driven setup looks like this:
- 1. Install the tool.
- ```bash
- brew install antopolskiy/tap/kanban-md
- ```
- 2. Go to your project directory and create a board.
- ```bash
- kanban-md init
- ```
- This creates `kanban/config.yml` and `kanban/tasks/`. The interactive setup
- offers to add `kanban/` to `.gitignore`; keep it tracked instead if the board
- should travel with the repository.
- 3. Install the bundled skills for your agents.
- ```bash
- # Install skills locally in this project
- kanban-md skill install
- # Or install them globally
- kanban-md skill install --global
- ```
- 4. Create tasks manually, or ask an agent to capture them.
- ```bash
- 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. Start the `kanban-based-development` skill with one agent. It will claim a
- task, create an isolated worktree, implement and verify the change, merge it,
- release the claim, and mark the task done. Once the workflow fits your
- project, run more agents and supervise their progress in the TUI.
- ```bash
- kanban-md tui
- ```
- 6. Adapt the local skill or `AGENTS.md` to the repository's own build, review,
- and release rules.
- ## Why kanban-md?
- Project management tools are designed for humans clicking buttons. kanban-md is designed for AI agents running commands and human supervision.
- - **Agent-first.** Token-efficient output (`--compact`), a single-step
- pick/claim/move workflow, structured JSON, and installable skills make the
- board practical inside non-interactive agent loops.
- - **Cooperative multi-agent coordination.** Claims reduce duplicate work, can be
- required by selected columns, and expire automatically when an agent stops
- renewing them. Claims are coordination leases, not a security or distributed-
- transaction boundary.
- - **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, Git,
- and `grep` can inspect the same source of truth without API credentials.
- - **No service dependency.** A single binary owns the local workflow; there is
- no database server, background daemon, or remote configuration 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.
- ```bash
- kanban-md tui
- ```
- 
- ## Installation
- ### Homebrew (macOS/Linux)
- ```bash
- brew install antopolskiy/tap/kanban-md
- ```
- ### Go
- ```bash
- 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.
- ## Quick start
- Agents can run these commands for you, but the same interface is useful for
- manual work and scripting.
- ```bash
- # 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 soft-delete it by moving it to archived
- 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:
- ```markdown
- ---
- 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.
- ```
- When kanban-md updates a task, it retains unrecognized YAML frontmatter
- properties, including exact numeric text, tags, lists, and maps with non-string
- keys. Anchors, aliases, and nested YAML merges are retained when their bindings
- stay entirely within these properties. This lets other tools keep their metadata
- through task edits. By default, additional properties do not appear in table,
- compact, or JSON output. You can explicitly select scalar values for the
- [property views below](#selected-task-properties). kanban-md's own fields remain authoritative,
- including fields you clear.
- An update refuses before changing the task file if an extra property aliases a
- canonical field or another anchor that cannot be retained safely. Top-level YAML
- merges, top-level alias keys, and custom tags on the whole frontmatter mapping
- also require manual editing before an update. A quoted `"<<"` property is allowed.
- Otherwise valid tasks with this metadata remain readable. If startup needs to
- repair an inconsistent task ID or filename and cannot safely rewrite its
- metadata, the command fails with an error until you correct the task manually.
- kanban-md reserializes its own fields after an update. It does not guarantee
- comments, indentation, quote style, original key placement, or byte-for-byte
- formatting.
- The `config.yml` tracks board settings. A newly initialized board currently
- uses schema version 12:
- ```yaml
- version: 12
- board:
- name: My Project
- tasks_dir: tasks
- statuses:
- - name: backlog
- show_duration: false
- - name: todo
- - name: in-progress
- require_claim: true
- - name: review
- require_claim: true
- - name: done
- show_duration: false
- - name: archived
- show_duration: false
- priorities:
- - low
- - medium
- - high
- - critical
- defaults:
- status: backlog
- priority: medium
- class: standard
- claim_timeout: 1h
- classes:
- - name: expedite
- wip_limit: 1
- bypass_column_wip: true
- - name: fixed-date
- - name: standard
- - name: intangible
- tui:
- title_lines: 2
- age_thresholds:
- - after: 0s
- color: "242"
- - after: 1h
- color: "34"
- - after: 24h
- color: "226"
- - after: 72h
- color: "208"
- - after: 168h
- color: "196"
- next_id: 1
- ```
- `config.yml` and `tasks/*.md` are authoritative. `activity.jsonl` is a
- best-effort, bounded audit log, and `.lock` is a transient coordination file
- used by operations that must serialize access. Neither is a hidden database.
- Direct task-file edits remain supported, but commands are the claim-aware
- mutation path while a task is actively claimed.
- ## Commands
- ### `init`
- Create a new kanban board.
- ```bash
- 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 interactively, kanban-md offers 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`.
- ```bash
- 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` | config default | Initial status |
- | `--priority` | config default | Priority level |
- | `--assignee` | | Person assigned |
- | `--tags` | | Comma-separated tags |
- | `--due` | | Due date (YYYY-MM-DD) |
- | `--estimate` | | Time estimate (e.g. 4h, 2d) |
- | `--class` | config default | Configured class of service |
- | `--parent` | | Parent task ID |
- | `--depends-on` | | Dependency task IDs (comma-separated) |
- | `--body` | | Task description (alias: `--description`) |
- | `--set-property KEY=LITERAL` | | Set a scalar property; repeat for multiple keys |
- ### `list`
- List tasks with filtering and sorting. Aliases: `ls`.
- ```bash
- 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 |
- | `--property KEY=LITERAL` | | Match one exact typed scalar value; repeat to combine with AND |
- | `--show-property KEY` | | Include a selected scalar in table, compact or JSON output; repeat for multiple keys |
- | `--group-by` | | Group counts by assignee, tag, class, priority, status, or `property:KEY` |
- | `--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.
- ```bash
- 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) |
- | `--show-property KEY` | Include a selected scalar on the task and its children; repeat for multiple keys |
- Children are ordered by task ID by default, matching `list --parent`.
- Set `children.detail_sort: property:reading_order` to use a numeric property
- instead. Finite numbers sort ascending, ties use task ID, and missing or
- unsuitable values follow in ID order. This changes detail views only, not list,
- board or pick order. See [selected task properties](#selected-task-properties).
- 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`](examples/issue-11-demo/README.md).
- ### `edit`
- Modify an existing task.
- ```bash
- 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) |
- | `--release` | Release claim on task |
- | `--class` | Set class of service |
- | `--set-property KEY=LITERAL` | Set or replace a scalar property; repeat for multiple keys |
- | `--clear-property KEY` | Remove a property, distinct from setting it to null |
- ### `move`
- Change a task's status.
- ```bash
- kanban-md move ID [STATUS]
- kanban-md move ID --next
- kanban-md move ID --prev
- kanban-md move 1,2,3 todo # batch move
- ```
- | Flag | Description |
- |------|-------------|
- | `--next` | Advance to next status in the configured order |
- | `--prev` | Move back to previous status |
- | `--claim` | Claim task for an agent |
- ### `handoff`
- Hand off a task for review. Moves to `review` status, appends a note, and optionally blocks/releases.
- ```bash
- kanban-md handoff ID --claim NAME [--note TEXT] [--block REASON] [-t] [--release]
- ```
- | Flag | Description |
- |------|-------------|
- | `--claim` | Claim name (required) |
- | `--note` | Handoff note to append to body |
- | `--timestamp`, `-t` | Prefix a timestamp line to the note |
- | `--block` | Mark task as blocked with reason |
- | `--release` | Release claim after handoff |
- ### `delete`
- Soft-delete a task by moving it to `archived`. Aliases: `rm`.
- ```bash
- kanban-md delete ID [--yes]
- kanban-md delete 1,2,3 --yes # batch delete
- ```
- Prompts for confirmation in interactive terminals. Use `--yes` (`-y`) to skip
- the prompt; it is required in non-interactive contexts and for batch deletion.
- The task file remains on disk and can still be listed with `--archived`.
- ### `archive`
- Move a task explicitly to the `archived` status without a confirmation prompt.
- Archived tasks are hidden from normal commands (`list`, `board`, `metrics`,
- `context`, TUI) but remain on disk. Use `--claim` when archiving a task with an
- active claim.
- ```bash
- kanban-md archive ID
- kanban-md archive ID --claim agent-1 # archive a task claimed by agent-1
- kanban-md archive 1,2,3 # batch archive
- ```
- To see archived tasks:
- ```bash
- kanban-md list --archived
- kanban-md list --status archived
- ```
- ### `board`
- Show a board summary with task counts per status, WIP utilization, blocked/overdue counts, and priority distribution. Aliases: `summary`.
- ```bash
- kanban-md board
- kanban-md board --watch # live-update on file changes
- ```
- | Flag | Default | Description |
- |------|---------|-------------|
- | `-w`, `--watch` | false | Live-update the board on file changes (Ctrl+C to stop) |
- | `--group-by` | | Group counts by assignee, tag, class, priority, status, or `property:KEY` |
- ### `pick`
- Find and claim the next available task in one operation. Designed for
- cooperative multi-agent workflows where ownership needs to be visible.
- ```bash
- kanban-md pick --claim agent-1
- kanban-md pick --claim agent-1 --status todo --move in-progress
- kanban-md pick --claim agent-1 --tags backend
- kanban-md pick --claim agent-1 --parent 42
- kanban-md pick --claim agent-1 --no-body
- ```
- | Flag | Default | Description |
- |------|---------|-------------|
- | `--claim` | (required) | Agent name to claim the task for |
- | `--status` | all non-terminal | One source status to pick from |
- | `--move` | | Also move picked task to this status |
- | `--tags` | | Only pick tasks matching at least one tag |
- | `--parent` | | Only pick tasks that are children of this parent task ID |
- | `--no-body` | false | Show only the pick confirmation line (skip full task details) |
- 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.
- 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.
- ### `agent-name`
- Generate a random two-word name for use with `--claim`. Uses the system dictionary when available, with a built-in word list as fallback.
- ```bash
- kanban-md agent-name
- # → quiet-storm
- kanban-md pick --claim $(kanban-md agent-name) --status todo --move in-progress
- ```
- ### `metrics`
- Show flow metrics: throughput, average lead/cycle time, flow efficiency, and aging work items.
- ```bash
- kanban-md metrics [--since YYYY-MM-DD]
- ```
- | Flag | Default | Description |
- |------|---------|-------------|
- | `--since` | | Only include tasks completed after this date |
- ### `log`
- Show the activity log of board mutations. Emitted actions include `create`,
- `edit`, `move`, `delete`, `block`, `unblock`, `claim`, `release`, `handoff`, and
- TUI priority changes.
- ```bash
- kanban-md log [FLAGS]
- ```
- | Flag | Default | Description |
- |------|---------|-------------|
- | `--since` | | Show entries after this date (YYYY-MM-DD) |
- | `--limit` | 0 | Maximum number of entries (most recent) |
- | `--action` | | Filter by exact action name |
- | `--task` | | Filter by task ID |
- ### `config`
- View or modify board configuration.
- ```bash
- kanban-md config # show all config values
- kanban-md config get KEY # get a single value
- kanban-md config set KEY VALUE # set a writable value
- ```
- Available keys:
- | Key | Writable | Description |
- |-----|----------|-------------|
- | `board.name` | yes | Board name |
- | `board.description` | yes | Board description |
- | `defaults.status` | yes | Default status for new tasks |
- | `defaults.priority` | yes | Default priority for new tasks |
- | `defaults.class` | yes | Default class of service for new tasks |
- | `statuses` | no | List of statuses |
- | `priorities` | no | List of priorities |
- | `tasks_dir` | no | Tasks directory name |
- | `wip_limits` | no | WIP limits per status |
- | `claim_timeout` | yes | Claim expiration duration (e.g. `1h`, `30m`) |
- | `classes` | no | Class of service definitions |
- | `tui.title_lines` | yes | Number of title lines shown in TUI cards |
- | `tui.hide_empty_columns` | yes | Hide columns with zero tasks in TUI |
- | `tui.narrow_threshold` | yes | Terminal width below which the single-column view is used; 0 is automatic |
- | `tui.age_thresholds` | no | TUI age color thresholds |
- | `next_id` | no | Next task ID |
- | `version` | no | Config schema version |
- ### `context`
- Generate a markdown summary of the board state for embedding in context files (e.g. `CLAUDE.md`, `AGENTS.md`).
- ```bash
- kanban-md context # print to stdout
- kanban-md context --write-to AGENTS.md # write/update in file
- kanban-md context --sections blocked,overdue # limit sections
- kanban-md context --days 14 # recently completed lookback
- ```
- | Flag | Default | Description |
- |------|---------|-------------|
- | `--write-to` | | Write context to file (creates or updates in-place) |
- | `--sections` | all | Comma-separated section filter |
- | `--days` | 7 | Recently completed lookback in days |
- Available section names: `in-progress`, `blocked`, `overdue`, `recently-completed`.
- 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.
- ## Interactive TUI
- `kanban-md tui` opens a full interactive terminal board with keyboard navigation. It auto-refreshes when task files change on disk.
- If no board exists in the current directory, `kanban-md tui` can initialize one and then offers to add that board directory to `.gitignore`.
- ```bash
- kanban-md tui # launch from any directory with a kanban/ board
- kanban-md tui --dir PATH # point to a specific kanban directory
- kanban-md tui --hide-empty-columns # override config and hide empty columns
- kanban-md tui --show-empty-columns # override config and show empty columns
- kanban-md tui --mouse # opt in to mouse navigation
- kanban-md tui --narrow # force the single-column layout at any width
- ```
- | Flag | Description |
- |------|-------------|
- | `--hide-empty-columns` | Hide empty columns for this run, overriding config |
- | `--show-empty-columns` | Show empty columns for this run, overriding config |
- | `--mouse` | Enable mouse navigation and drag-and-drop |
- | `--narrow` | Force the single-column layout at any terminal width |
- Set `tui.hide_empty_columns` in `config.yml` to control the default behavior.
- > **Note:** Older releases shipped a standalone `kanban-md-tui` binary. It has been retired — use `kanban-md tui` instead.
- In create/edit dialogs, text fields support cursor-based editing (`←/→`, `Home/End`, `Backspace`, `Delete`).
- Opening a task shows its known ancestor path and the same direct-child list and
- roll-up as `show`. Archived ancestors remain visible as context but cannot be
- opened; archived children remain hidden. Search and level filters control cards,
- not which active relations you can open in details.
- ### Explore task relations
- In details, `Tab` and `Shift+Tab` move the relation focus in reading order;
- `Enter` opens it. `Esc` or `Backspace` takes one step back, restoring your
- previous task, scroll position and relation focus. `q` closes the entire chain
- and returns to the board, keeping its search, level and sort settings. `j`/`k`,
- arrow keys and `g`/`G` still scroll the detail content.
- Ancestors appear root-first. On a milestone → epic → story path, the first
- `Tab` focuses the milestone; `Tab`, `Tab`, `Enter` opens the immediate epic.
- From that epic, `Tab`, `Enter` opens the milestone. Two `Esc` presses retrace
- those steps. Missing parent IDs and self/cycle markers remain visible rather
- than being repaired by navigation.
- ### Focus one hierarchy level
- In board mode, `v` cycles all tasks → the numeric levels present among active
- tasks → unknown depth, if present → all. Root tasks are `L0`, their children
- `L1`, and so on. Boards with hierarchy show these text labels beside task IDs
- and the active `level[...]` in the status line. Flat boards keep their usual
- cards by default. While typing a search, `v` is ordinary text.
- Levels come from parent links, including archived ancestors, and are not task
- types or stored fields. Missing/self-parent links use an effective level-zero
- root; a multi-task cycle and tasks reaching it have `L?`. The level filter and
- title/tag/ID search combine with AND. Neither writes task data.
- Task bodies are rendered as Markdown using the terminal's default foreground
- for the main text, so they remain readable when a terminal switches between
- light and dark themes while the TUI is running.
- ### Narrow mode (small terminals)
- On terminals too narrow to show every column side by side — a phone over SSH, a
- split pane — the board automatically switches to a single-column layout. It shows
- one column at a time, full width, under a two-line header: a tab strip of all
- columns (the active one highlighted) on top, and the active column's own full
- name, count, and WIP limit below. Card titles stay readable instead of being
- crushed to a few characters per column.
- Switch columns with `←`/`→`, `h`/`l`, or `Tab`/`Shift+Tab`. With `--mouse`, tap a
- tab to jump straight to that column; tapping a card selects it as usual.
- Narrow mode activates automatically once columns can no longer get a usable
- width. To force or tune it:
- ```bash
- kanban-md tui --narrow # force narrow mode for this run
- kanban-md config set tui.narrow_threshold 80 # persist a custom trigger width
- ```
- Set `tui.narrow_threshold` with `kanban-md config set` (or directly in
- `config.yml`) to override the automatic trigger — the board goes narrow below
- that terminal width. Use `0` for automatic behavior or `1` to effectively
- disable narrow mode.
- ### Mouse mode
- Mouse controls are opt-in, so the normal keyboard-only TUI remains unchanged.
- Start mouse mode with:
- ```bash
- kanban-md tui --mouse
- ```
- | Mouse action | Result |
- |--------------|--------|
- | Click a card | Select the card and synchronize keyboard navigation |
- | Double-click the same card within 500 ms | Open its detail view |
- | Click an active relation row in details | Open that task, including wrapped rows |
- | Click `Back` | Take one detail-history step, or return to the board when history is empty |
- | Wheel over a column | Activate that column and move its selection one card |
- | Wheel in a detail view | Scroll the task body three lines |
- | Hold a card, drag to another visible column, and release | Move the task to that status |
- The entire rendered destination column is a drop target, including its header,
- cards, and visible empty area. Releasing over the source column or outside a
- valid column cancels the drag. Keyboard shortcuts continue to work while mouse
- mode is active, so both input styles can be mixed freely.
- The board status line begins with the card count and `? help`, followed by the
- optional mouse indicator and the remaining actions. Shortcut characters are
- highlighted inside their action labels so the essential hints survive narrow
- terminal widths.
- Status moves made in the TUI preserve an existing task claim. If an unclaimed
- task enters a `require_claim` status, the TUI automatically claims it using the
- local hostname; that claim remains attached if the task later moves elsewhere.
- Terminals commonly reserve a modifier such as Shift or Option/Alt to bypass
- application mouse reporting for native text selection. The exact modifier is
- terminal-dependent; use the terminal's normal selection shortcut or omit
- `--mouse` when native selection is preferred.
- ### Keyboard shortcuts
- | Key | Action |
- |-----|--------|
- | `h` / `l` | Move between columns |
- | `j` / `k` | Move between tasks within a column |
- | `Enter` | View task details |
- | `c` | Create task in current column |
- | `e` | Edit selected task (same 4-step flow as create) |
- | `E` | Open the selected task's Markdown file in `$VISUAL`, then `$EDITOR`, then `vi` when available |
- | `m` | Move task to a different status (picker dialog) |
- | `n` / `p` | Move task to next / previous status |
- | `d` | Soft-delete (archive) task with confirmation |
- | `s` | Cycle the sort field (priority → created → updated → title) |
- | `S` | Reverse the sort direction |
- | `/` | 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 |
- | `v` | In board mode, cycle exact hierarchy levels; session-only |
- | `Tab` / `Shift+Tab` in details | Focus relations in reading order |
- | `Enter` in details | Open the focused relation |
- | `Esc` / `Backspace` in details | Go back one navigation step |
- | `r` | Refresh board |
- | `?` | Show help |
- | `q` | Quit from the board; close the whole detail chain from details |
- | `Ctrl+C` | Quit |
- ## Global flags
- These work with any command:
- | Flag | Description |
- |------|-------------|
- | `--json` | Force JSON output |
- | `--table` | Force table output (default) |
- | `--compact` / `--oneline` | Compact one-line-per-record output |
- | `--dir` | Path to kanban directory (overrides auto-detection) |
- | `--no-color` | Disable color output (also respects `NO_COLOR` env var) |
- ### Output format
- The default output format is **table** (human-readable). Use flags to switch:
- ```bash
- # Default: table
- kanban-md list --status todo
- # Compact: one line per task, ideal for AI agents
- kanban-md list --compact
- # JSON: for scripting and piping
- kanban-md list --json | jq '.[].title'
- ```
- Set the `KANBAN_OUTPUT` environment variable to change the default: `json`, `table`, `compact`, or `oneline`.
- Override priority: `--json`/`--table`/`--compact` flags > `KANBAN_OUTPUT` env var > table default.
- ## Configuration
- 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.
- Use `--dir` to point to a specific board:
- ```bash
- kanban-md --dir /path/to/kanban list
- ```
- ### Custom statuses
- Define your own workflow columns:
- ```bash
- kanban-md init --statuses "open,in-progress,blocked,closed"
- ```
- The order matters — it defines the progression for `move --next` and `move --prev`, and the sort order for `list --sort status`.
- ### Custom priorities
- Edit `config.yml` directly to customize priorities:
- ```yaml
- priorities:
- - trivial
- - normal
- - urgent
- - showstopper
- defaults:
- priority: normal
- ```
- Priority order runs from lowest to highest. `list --sort priority` shows the
- highest configured priority first by default; use `--reverse` for lowest first.
- ### Selected task properties
- Use your own top-level scalar properties for categories, reading order or other
- workflow data, without adding a task type or rank to the core model:
- ```bash
- kanban-md create "Draft chapter" --parent 1 \
- --set-property kind=chapter --set-property reading_order=20
- kanban-md edit 2 --set-property reading_order=10
- kanban-md list --property kind=chapter --show-property reading_order
- kanban-md list --group-by property:kind
- kanban-md show 1 --json --show-property kind --show-property reading_order
- ```
- Repeat `--set-property`, `--clear-property`, `--property` and `--show-property`
- for different keys. Keys are case-sensitive literal names matching
- `[A-Za-z_][A-Za-z0-9_.-]*`; a dot is part of the key, not a nested path.
- Task-owned names such as `status`, `priority`, `parent`, `body` and `file` are
- reserved: use their existing flags. Duplicate keys and simultaneous set/clear
- of the same key are errors. Multi-task edits retain the normal per-task batch
- behavior, not an all-or-nothing transaction.
- CLI literals support a bare string, a JSON-quoted string, a decimal/scientific
- number, lowercase `true`/`false`, or `null`. Shell quotes protect the argument;
- inner JSON quotes choose a string instead of a number or boolean:
- ```bash
- kanban-md edit 2 --set-property reading_order=20 # number
- kanban-md edit 2 --set-property 'reading_order="20"' # string, not a numeric order
- kanban-md edit 2 --set-property 'note=""' # empty string
- kanban-md edit 2 --set-property note=null # present null
- kanban-md edit 2 --clear-property note # absent key
- ```
- The authoring grammar does not evaluate YAML tags, aliases, arrays or maps.
- Use strict JSON numeric spelling on the CLI: quote `01`, `+20`, `.5`, `0x10`
- or `1_000` if you mean text. Reading existing YAML numeric forms is exact,
- including large values and base-prefixed integers; numeric-looking strings
- remain strings. Property equality is typed and exact. Repeated filters and
- ordinary filters combine with AND. Missing and unsupported values never match,
- including a filter for null.
- Edit these optional view settings directly in `config.yml`:
- ```yaml
- group_orders:
- property:kind: [milestone, chapter, story, bug]
- display:
- compact_fields: [status, property:kind]
- tui:
- card_fields: [property:kind]
- children:
- detail_sort: property:reading_order
- ```
- Omit them to retain `[status/priority]` compact chips, the TUI priority badge
- and ID-ordered children. Compact/card fields accept one or two distinct choices
- from `status`, `priority`, `class` or `property:KEY`; empty and null lists are
- invalid. Omit the field to use its defaults. Restart an open TUI after changing
- these config settings; its refresh command reloads tasks, not view settings.
- Compact fields apply to `list`, `show` and `pick`; other command confirmations
- keep their existing format.
- Child detail sort accepts `id` or one numeric property selector. Config version
- 12 migration preserves the old effective defaults and does not rewrite tasks.
- Group order is a presentation preference, not an enum. Configured values appear
- first; other strings follow alphabetically, then numbers, booleans and null.
- Missing or unsupported values share the last `(unclassified)` group. Scalar
- group labels are quoted/typed to keep text `"20"` distinct from number `20`.
- For example, a typo such as `chapetr` remains visible in the grouped summary;
- correct it with `edit ID --set-property kind=chapter`. Grouped output contains
- counts, not task records, so it cannot be combined with `--show-property`.
- Only `list` and `show` accept `--show-property`. It adds selected columns/tokens
- to human output and a `properties` object to each JSON task or child record.
- Missing keys are omitted, explicit null is present as null, and unsupported
- values are omitted with a warning. Nested, alias, timestamp, binary,
- custom-tagged and non-finite values remain preserved but are not selected
- scalars. Unselected metadata never enters task JSON. Display and sort settings
- do not select JSON values; use `--show-property` explicitly.
- Human badges use `KEY=--` for missing, `KEY=?` for unsupported and `KEY=null`
- for null; strings are quoted. Control characters are escaped and long badge
- values are shortened. Details show the selected properties that explain the
- view; JSON keeps their complete supported values when explicitly requested.
- Child ordering never changes priority, pick, dependencies, claims or WIP.
- Zero, negative and fractional numbers are valid; sparse values such as 10, 20,
- 30 leave room for inserts. Reparenting or clearing a parent retains the property.
- To reset placement when detaching, clear both in one edit:
- ```bash
- kanban-md edit 2 --clear-parent --clear-property reading_order
- ```
- An explicit property replacement/removal can still refuse if it would leave
- another retained YAML alias unsafe. The error leaves the task file unchanged
- and asks for manual frontmatter editing; unrelated values are not rewritten
- to make the edit succeed.
- ## Shell completions
- Generate completions for your shell:
- ```bash
- # bash
- source <(kanban-md completion bash)
- # zsh
- kanban-md completion zsh > "${fpath[1]}/_kanban-md"
- # fish
- kanban-md completion fish | source
- # PowerShell
- kanban-md completion powershell | Out-String | Invoke-Expression
- ```
- ## Agent skills
- 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.
- Two skills are included:
- | Skill | Description |
- |-------|-------------|
- | **kanban-md** | Command reference, decision trees, and workflows for managing tasks via CLI. Auto-triggered when an agent encounters task-related work. |
- | **kanban-based-development** | Full autonomous development workflow — multi-agent claim semantics, git worktrees for isolation, and a strict status lifecycle (in-progress → review → done). |
- ```bash
- # Install skills for all detected agents (Claude Code, Codex, Cursor, OpenClaw)
- kanban-md skill install
- # Check if installed skills are up to date
- kanban-md skill check
- # Update skills to match current CLI version
- kanban-md skill update
- # Preview one skill
- kanban-md skill show --skill kanban-md
- ```
- 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.
- ## Multi-agent workflow
- kanban-md coordinates concurrent work by multiple agents and humans through
- cooperative claims and classes of service.
- ### Claims
- Claims are cooperative leases: an agent claims a task before working on it, and
- well-behaved agents exclude tasks with active claims from selection. Claims
- expire after the configured timeout (default: 1 hour). They reduce collisions,
- but they are not a security boundary or a transactional distributed lock.
- 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.
- 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.
- ```bash
- # Agent picks next available task
- kanban-md pick --claim agent-1 --move in-progress
- # Move to review (require_claim enforced — must include --claim)
- kanban-md move 5 review --claim agent-1
- # Agent finishes and releases
- kanban-md edit 5 --release
- kanban-md move 5 done
- # Another agent picks from a specific queue
- kanban-md pick --claim agent-2 --status todo --tags backend
- ```
- ### Classes of service
- Tasks can have a class of service that affects WIP limits and pick priority:
- | Class | Behavior |
- |-------|----------|
- | **expedite** | Bypasses column WIP limits. Has its own board-wide WIP limit (default: 1). Picked first. |
- | **fixed-date** | Picked by earliest due date within its priority tier. |
- | **standard** | Default class. Normal WIP and priority rules. |
- | **intangible** | Picked last. For background/maintenance work. |
- ```bash
- kanban-md create "Critical hotfix" --class expedite --priority critical
- kanban-md create "Q2 deadline feature" --class fixed-date --due 2026-06-30
- ```
- ### Swimlanes
- Group board or list views by any field to see work distribution:
- ```bash
- kanban-md board --group-by assignee # who is working on what
- kanban-md board --group-by class # class of service breakdown
- kanban-md list --group-by tag # work by tag
- kanban-md list --group-by priority # priority distribution
- ```
- ## Design principles
- kanban-md provides orthogonal, composable workflow primitives. Development is
- one use, not the definition of its domain. These principles guide new features
- and reviews; they are not a claim that every existing implementation meets them.
- 1. Compose workflows; make new domain concepts earn their place. Prefer shared
- capabilities over built-in concepts named after one workflow.
- 2. Choose the smallest capability that actually solves the need. Count user
- effort and maintenance cost; a generic framework is not automatically simpler.
- 3. Keep the basic board complete; make workflow policy optional. Extras should
- impose no required setup or default clutter. Usability and data protection
- still deserve sensible defaults.
- 4. Give each value and action one explicit meaning. Separate task data, relations,
- views, and policy. Display order must not silently become execution order.
- 5. Keep local files authoritative and the core independently useful. Optional
- integrations must not make ordinary board use depend on accounts or services.
- 6. Preserve contracts across interfaces, upgrades, and writers. Keep mutations
- consistent, agent commands non-interactive, and existing boards compatible.
- The project-local [principal-owner skill](.agents/skills/kanban-md-principal-owner/SKILL.md)
- contains the review criteria, tradeoffs, and decision format. It is contributor
- guidance, not one of the workflow skills installed into users' projects.
- ## Development
- ```bash
- # Build
- make build
- # Run all tests (unit + e2e)
- make test
- # Run only e2e tests
- make test-e2e
- # Lint
- make lint
- # Lint with autofix
- make lint-fix
- # Full pipeline
- make all
- ```
- ## License
- [MIT](LICENSE)
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.