Description

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 .md files 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.html is a self-contained app you can open in any browser

Installation

npm install -g kandown

Requirements: Node.js 18+

Usage

Initialize in any project

cd my-project
kandown init

This creates two folders at your project root:

.kandown/             # config + web UI + agent docs
├── kandown.html      # Single-file web app
├── kandown.json      # Project config (columns, appearance)
├── AGENT.md          # AI-agent quick reference
└── AGENT_KANDOWN.md  # Full agent reference

tasks/                # Task files (source of truth)
├── t1.md             # One .md file per task
└── archive/          # Archived tasks live here

Layout note: tasks live at the project root in ./tasks/, not inside .kandown/. This keeps config and data cleanly separated. If you're upgrading from an older version with tasks in .kandown/tasks/, the CLI will move them automatically the first time you run it — nothing to do.

Launch the board

kandown

This 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.

CLI Commands

| 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 |

Features

Board & Views

| 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 |

Task Management

| 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 |

Appearance & UX

| 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 |

AI Agent Integration

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 |

Keyboard Shortcuts

| 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) |

TUI extras

| 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 |

Data Model

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 middleware

Contributing

Contributions are welcome! Please read the existing code style and conventions before submitting PRs.

Development Setup

git clone https://github.com/vava-nessa/kandown.git
cd kandown
pnpm install
pnpm dev          # Web UI at localhost:5176

Scripts

| 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 |

License

MIT — use it, fork it, ship it.