File-based Kanban board backed by plain Markdown.
Zero backend · Zero database · No account · AI-agent friendly
Kandown is a local-first Kanban board where your tasks live as plain Markdown files. No cloud, no account, no vendor lock-in — just a .kandown/ folder in your project that you own forever.
- Your data is portable — tasks are
.mdfiles versioned with git, readable by any text editor or AI agent - AI-agent friendly — Claude, Codex, Gemini, Goose, Aider, and OpenCode can read and update tasks directly
- Dual interface — a polished web UI + a full terminal TUI, both running entirely offline
- Single-file deployment —
kandown.htmlis a self-contained app you can open in any browser
npm install -g kandownRequirements: Node.js 18+
cd my-project
kandown initThis creates a .kandown/ folder with:
.kandown/
├── kandown.html # Single-file web app
├── kandown.json # Project config (columns, appearance)
├── tasks/ # One .md file per task
└── AGENT.md # AI-agent quick reference
kandownThis starts a per-project local web daemon, then opens:
- A web UI in your browser (board view, list view, task editor)
- A terminal TUI for keyboard-driven workflow (works over SSH, no browser needed)
The web daemon stays alive after you quit the TUI so the browser keeps working. Stop or restart it anytime from the TUI with d, or from the CLI with kandown daemon stop.
| Command | Description |
|---|---|
kandown |
Launch web UI + board TUI |
kandown init |
Initialize in current project |
kandown board |
TUI only (no browser) |
kandown settings |
Terminal settings editor |
kandown daemon status |
Show this project's web daemon status |
kandown daemon start |
Start/reconnect this project's web daemon |
kandown daemon stop |
Stop this project's web daemon |
kandown update |
Update kandown.html to latest |
kandown help |
CLI help |
| Feature | Description |
|---|---|
| Board view | Horizontal kanban with drag-and-drop |
| List view | Dense table with filters & search |
| Content search | Search titles, body, subtasks, tags, assignee, priority |
| Command palette | ⌘K / Ctrl+K for quick actions |
| Custom columns | Add, rename, delete columns freely |
| Guarded deletion | Double-click to delete — no accidents |
| Feature | Description |
|---|---|
| Rich task drawer | WYSIWYG markdown editor for title, metadata, subtasks, body |
| Subtasks | Full checklist with progress tracking on cards |
| Metadata fields | Priority, assignee, tags, due date, owner type |
| Owner filtering | Filter human vs AI-agent tasks separately |
| External-change detection | Warns when files are modified outside the app |
| Feature | Description |
|---|---|
| 5 built-in skins | Kandown, Graphite, Sage, Cobalt, Rose |
| Theme modes | Auto (system), Light, Dark |
| 5 font stacks | Inter, System, Serif, Mono, Rounded |
| Animated backgrounds | WebGL fluid simulation (LiquidEther) |
| 48 languages | Full i18n support |
| Notifications | Browser + sound alerts for status changes, edits, completions |
Press a in the board TUI to launch an AI agent on any task. Supported agents:
| Agent | Binary | Launch mode |
|---|---|---|
| Claude Code | claude |
Interactive session |
| OpenAI Codex | codex |
Interactive session |
| Gemini CLI | gemini |
-p flag for initial prompt |
| Goose | goose |
run --text for non-interactive |
| Aider | aider |
--message for initial prompt |
| OpenCode | opencode |
TUI, context written to /tmp |
| Shortcut | Action |
|---|---|
⌘K / Ctrl+K |
Command palette |
⌘1 / Ctrl+1 |
Board view |
⌘2 / Ctrl+2 |
List view |
N |
New task |
R |
Reload from disk |
/ |
Focus search |
Esc |
Close drawer / palette |
⌘S / Ctrl+S |
Save task |
⌘⌫ / Ctrl+Backspace |
Delete task (with confirmation) |
| Shortcut / gesture | Action |
|---|---|
d |
Start/stop the per-project web daemon |
| Mouse drag task | Move a task between columns in the terminal |
m |
Open the focused task context menu |
r |
Reload board from disk |
Each task is a standalone Markdown file:
---
id: t1
title: Implement user auth
status: Todo
priority: P1
tags: [backend, security]
assignee: chacha
created: 2026-04-10
---
# Implement user auth
## Context
Why this task exists.
## Subtasks
- [ ] Set up OAuth provider
- [x] Create user model
- [ ] Add session middlewareContributions are welcome! Please read the existing code style and conventions before submitting PRs.
git clone https://github.com/vava-nessa/kandown.git
cd kandown
pnpm install
pnpm dev # Web UI at localhost:5176| Script | Description |
|---|---|
pnpm dev |
Vite dev server for web UI |
pnpm dev:cli |
Watch-mode build for CLI TUI |
pnpm build |
Full build: typecheck → web app → CLI |
pnpm build:cli |
CLI TUI build only |
pnpm preview |
Preview production build |
pnpm typecheck |
TypeScript check |
MIT — use it, fork it, ship it.
Quick Start · Features · CLI · AI Agents