![\"Kandown](\"logo.svg\")
\n\n \n
\n Too Many Ideas, Not Enough Agents.
\n A local-first Kanban board where every task is a Markdown file you own forever.
\n Zero backend · Zero database · No account · Built for working alongside AI agents\n
\n ![\"npm](\"https://img.shields.io/npm/v/kandown?color=cb3837&label=npm\")
![\"npm](\"https://img.shields.io/npm/dm/kandown?color=blue\")
![\"Reddit](\"https://img.shields.io/badge/Reddit-r%2Fkandown-FF4500?logo=reddit&logoColor=white\"){kind=icon}
![\"MIT](\"https://img.shields.io/badge/license-MIT-green\"){kind=icon}
![\"100%](\"https://img.shields.io/badge/local--first-100%25-orange\"){kind=icon}
\n kandown.dev ·\n Documentation ·\n Extensions ·\n Changelog ·\n Reddit (r/kandown)\n
\n\n\n Quick start ·\n For AI agents ·\n CLI ·\n Features ·\n Contributing\n
\n\n> [!WARNING]\n> **Active development — do not use in production yet.** Kandown is a build-in-public project. The first stable release will be **v1.0.0**. Expect breaking changes, missing features and rough edges before then. Use at your own risk.\n\n---\n\n## What it is\n\nKandown drops a `tasks/` folder into your project and gives you three ways to work\nwith it: a polished web board, a full terminal UI, and a scriptable CLI. All three\nread and write the same plain Markdown files.\n\n- **Your data is just files.** One `.md` per task, versioned in git, readable by any\n editor, any script, any AI agent. Nothing to export, nothing to lose.\n- **Files named after what they are.** `tasks/t232_remove_dead_code.md`, not\n `tasks/t232.md`, so a `git diff --stat`, a PR file list and your editor tabs all\n read as English. A title that starts with a bracket category (`[UI] Fix the\n login button`) carries it through into the filename as an uppercase segment\n between the id and the prose (`t232_UI_fix_login_button.md`), so the file's\n taxonomy is visible at a glance too. The id stays the identifier: renaming a\n file never breaks a dependency or a link, and bracket changes in the web\n drawer auto-rename the file so the taxonomy cannot drift.\n- **Agents are first-class users**, not an integration. Claude Code, Codex, Gemini\n CLI, Goose, Aider and OpenCode all drive the board directly.\n- **Fully offline.** No account, no cloud, no telemetry. The web UI is one\n self-contained HTML file you can open anywhere.\n\n---\n\n## Quick start\n\n```bash\nnpm install -g kandown # Node.js 18+\ncd my-project\nkandown init\nkandown\n```\n\n`kandown init` creates two folders at your project root:\n\n```\ntasks/ # your tasks — the source of truth\n├── t1_add_dark_mode.md # one Markdown file per task, named after it\n└── archive/ # archived tasks live here\n\n.kandown/ # config + web UI + workflow data\n├── kandown.json # columns, theme, notifications, agents\n├── kandown.html # the web app, one self-contained file\n├── kandown_work.md # optional: your project's agent instructions\n├── workflows/ # optional: project-local workflow packages\n└── skills/ # optional: project-local Markdown skills\n```\n\n`kandown` then starts a small local daemon and opens both a **web board** in your\nbrowser and a **terminal UI** in your shell. The daemon outlives the TUI, so the\nbrowser keeps working after you quit — stop it with `d` in the TUI or\n`kandown daemon stop`.\n\nTasks live at your project root rather than inside `.kandown/` so that config and\ndata stay cleanly separated. Upgrading from an older layout? The CLI moves them for\nyou on first run.\n\n---\n\n## For AI agents\n\nThis is the part that makes kandown different, so it is worth two minutes.\n\n### One command for context\n\n```bash\nkandown work\n```\n\nThat prints one deterministic nine-layer Markdown document: the immutable Kandown\ncore, the project's real column roles and available commands, enabled extension\nguidance, the active workflow, tracking cadence, additive skills, global and\nproject instructions, then a targeted task context or compact board digest.\n\nOne call, full context. `kandown init` adds a single line to your `AGENTS.md` /\n`CLAUDE.md` pointing at it — no block of rules copied in to go stale.\n\nSettings provides three agent-work tabs: **Workflow**, **Skills**, and **Kandown\nWork**. Select one exclusive workflow, add compatible skills, tune instruction\ndetail and tracking cadence independently, assign semantic roles to freely named\ncolumns, edit project instructions, and inspect the exact compiler output.\nThe full-screen reader keeps the entire document accessible and shows portable\ntoken, word, and character estimates before an agent receives it.\n\n### Scriptable, composable, offline\n\n```bash\nkandown list --json | jq '.[] | select(.priority==\"P1\")'\nID=$(kandown create \"Refactor auth middleware\" -p P1 -t backend)\nkandown move \"$ID\" Done\nkandown commit -m \"tasks: add auth refactor\"\n```\n\n**Output contract:** stdout carries data only — ids, JSON, tables. Everything\ndecorative (`✓ Created…`, warnings, errors) goes to stderr. So `$(kandown create\n…)` captures exactly one id, and `--json | jq` never chokes on a checkmark. Exit\ncode `0` on success, non-zero on failure.\n\n**Task commands never use the network.** Registry access occurs only when a human\nexplicitly opens a store or runs a store/install/update command. Workflow installs\nare pinned, checksum-verified, validated, and updated only after a displayed diff.\n\n### MCP\n\n```bash\nkandown mcp # stdio MCP server\nclaude mcp add kandown -- kandown mcp\n```\n\n### Launching agents from the board\n\nPress `a` on any task in the terminal UI. One key does both halves of the job:\nit writes `assignee: