Quick start

Two minutes, four commands.

1. Initialize

cd my-project
kandown init

This creates two folders at your project root:

tasks/                # your tasks — the source of truth
├── t1.md             # one Markdown file per task
└── archive/          # archived tasks live here

.kandown/             # config + web UI + agent docs
├── kandown.json      # columns, theme, notifications, agents
├── kandown.html      # the web app, one self-contained file
├── instructions.md   # optional: your project's agent instructions
└── AGENT*.md         # agent reference, kept in sync with the CLI

It also appends a single line to your AGENTS.md / CLAUDE.md pointing agents at kandown work — one line, not a block of rules that will go stale.

2. Open the board

kandown

This starts a small local daemon, opens the web board in your browser and a terminal UI in your shell. Both are live views of the same files.

The daemon outlives the terminal UI on purpose — quit the TUI and your browser tab keeps working. Stop it with d in the TUI, or:

kandown daemon stop

Prefer no browser at all? kandown board gives you the terminal UI only.

3. Create a task

From the web board, press N. From the terminal UI, press n. From a script:

kandown create "Refactor auth middleware" -p P1 -t backend -a chacha

That prints the new task's id — and nothing else — on stdout, so you can capture it:

ID=$(kandown create "Add rate limiting" -p P1)
kandown move "$ID" "In progress"

The quick-add box in the UI parses the same information out of one line:

Fix login p1 #backend @chacha due:friday

4. Point an agent at it

kandown work

Everything an agent needs, as Markdown on stdout: the rules, your project instructions, a live board digest, and the next actionable task — computed as the unblocked task closest to done with the highest priority.

Wire it into an MCP-capable client instead, if you prefer:

claude mcp add kandown -- kandown mcp

Or select a task in the terminal UI and press a to launch Claude Code, Codex, Gemini CLI, Goose, Aider or OpenCode directly on it.

5. Commit

Tasks are files, so they belong in your history:

kandown commit -m "tasks: plan the auth refactor"

That stages tasks/ and .kandown/kandown.json and commits them. Plain git add works exactly as well — the command is a convenience, not a requirement.

Where to go next

• Tasks — fields, subtasks, dependencies, templates
• For AI agents — the part that makes Kandown different
• CLI reference — every command and flag