Kandown

A lightweight, markdown-inspired Kanban board for developers — backed by a plain YAML file that lives right in your project repository.

What is Kandown?

Kandown is a simple Kanban board app that stores all your tasks in a single human-readable YAML file. Because it's just a file, you can:

• Version-control your backlog alongside your code in Git
• Edit tasks manually in any text editor
• Share and review your backlog like any other project file

It ships as a Python CLI that starts a local web server, giving you a clean drag-and-drop board in your browser. No database, no cloud account, no complex setup required.

🎯 Quick Start — No Installation Needed

Not a developer? This is the recommended option for you.

Try Kandown instantly in your browser — no install, no sign-up, your data stays private and local:

👉 Open Kandown in your browser

Want to see a real board? Check out our own project backlog.

The hosted static site runs entirely in your browser:

• localStorage mode (default, all browsers) — data is saved in your browser
• File System mode (Chrome / Edge only) — read and write a real backlog.yaml file on your computer

Features

• 🗂️ Kanban board — drag-and-drop tasks between Icebox, To Do, In Progress, and Done columns
• ✏️ Markdown descriptions — write rich task descriptions with full Markdown support
• ✅ Interactive checkboxes — check off items directly on the card
• 🏷️ Tags and task types — organise tasks with custom tags and built-in types (feature, bug, chore, epic, experiment, request)
• 🖼️ Paste images — paste screenshots directly into task descriptions
• 📄 YAML-backed storage — all tasks live in a plain, human-readable backlog.yaml file
• 🌐 Browser-only mode — use without installing anything via the hosted static site
• 🔄 JetBrains IDE integration — view and navigate tasks from any JetBrains IDE
• 🚀 CLI server — start a local server with one command, auto-creates the YAML file if missing
• 🌙 Dark mode — easy on the eyes

Getting Started

For Developers — CLI Mode

Install and run with a single command:

# Run directly without installing (requires uv)
uvx kandown [YAML_FILE]

# Or install permanently
uv tool install kandown
pipx install kandown
pip install kandown

Start the server

# Start with the default backlog.yaml (created automatically if missing)
kandown

# Start with a specific file on a custom port
kandown --port 8080 myproject.yaml

Open your browser at http://127.0.0.1:5001 (default port) to view the board.

CLI Options

For Non-Technical Users — Static Site

The easiest way to use Kandown is through the hosted static site. No installation required — just open it in your browser and start adding tasks.

Your data is stored in your browser (localStorage) by default, so it persists between visits without any server. Chrome and Edge users can also connect directly to a folder on their computer to read and write real YAML files.

Storage Modes

Kandown supports four storage modes:

Using File System Mode (Chrome / Edge)

1. Open the hosted site in Chrome or Edge
2. Click the ⚙️ settings button
3. Under Storage Mode, click 📂 Use File System (Chrome/Edge)
4. Select a folder — Kandown will read/write backlog.yaml in that folder
5. Work as normal; all changes are saved directly to the file

Sharing a Board (Read-Only)

Anyone with access to a publicly hosted YAML file can view your board in read-only mode:

https://eruvanos.github.io/kandown/?backlog=https://example.com/path/to/backlog.yaml

The file must be accessible via HTTP and have CORS enabled (GitHub raw URLs work well).

Deploying Your Own Static Site

Fork the repository, enable GitHub Pages (Settings → Pages → Source: GitHub Actions), and push to main. The included workflow will build and deploy the static site automatically.

Settings

The settings panel (⚙️ button) exposes the following options. Availability depends on the active storage mode:

Tip: Settings are stored together with your tasks inside the backlog.yaml file in CLI and File System modes, so they roam with your project.

JetBrains IDE Integration

Connect Kandown to any JetBrains IDE using the built-in Tasks & Contexts feature:

1. Open IDE settings → Tools → Tasks → Servers
2. Add a new Generic server with these details:

License

MIT License