Kandown

https://kandown.dev/docs
Admin
Kandown is a local-first task management tool where each task is a Markdown file, providing a web...
Tokens:13,982
Snippets:162
Trust Score:2.7
Update:1 month ago
Show doc for...
Tokens:
Raw
### Set up the repository with git clone, pnpm install, and pnpm dev

Source: https://kandown.dev/docs/project/contributing.md

Clones the repository, installs dependencies with pnpm (which also installs git hooks), and starts the development server. Use pnpm, not npm, because the lockfile is pnpm's.

```bash
git clone https://github.com/vava-nessa/kandown.git
cd kandown
pnpm install          # also installs the git hooks
pnpm dev              # web UI at localhost:5176
```

--------------------------------

### Install and initialize Kandown

Source: https://kandown.dev

Full local experience: install Kandown globally, then initialize a project and launch the web board.

```bash
npm install -g kandown
```

```bash
kandown init && kandown
```

--------------------------------

### Install Kandown globally with npm

Source: https://kandown.dev/docs/installation.md

Install the Kandown CLI globally using npm.

```bash
npm install -g kandown
```

--------------------------------

### Complete task file example

Source: https://kandown.dev/docs/reference/data-model.md

Complete example of a task file showing frontmatter fields and body conventions. The frontmatter includes id, title, status, priority, tags, assignee, depends_on, and created. The body uses ## Context for the description and ## Subtasks with a Markdown checklist, where completed items can carry an indented report: line.

```markdown
---
id: t1
title: Implement user auth
status: Todo
priority: P1
tags: [backend, security]
assignee: chacha
depends_on: [t7]
created: 2026-04-10
---

# Implement user auth

## Context
Why this task exists.

## Subtasks
- [x] Create user model
  report: Added src/models/user.ts with the schema and migrations.
- [ ] Set up OAuth provider
```

--------------------------------

### Example .kandown/kandown_work.md content

Source: https://kandown.dev/docs/agents/instructions.md

Example content for .kandown/kandown_work.md covering stack, conventions, working style, and do-not-touch rules. Use it to capture project-specific details that agents cannot infer from the code.

```markdown
## Stack
- pnpm, always. Never npm or yarn; the lockfile is pnpm's.
- Vitest for tests: `pnpm test`. There is no jest config despite the old comments.

## Conventions
- Conventional commits, imperative mood, English.
- No `any` in TypeScript. Use `unknown` plus a type guard.
- UI strings are authored in English and translated from there.

## Working style
- Update the task file as you go, not at the end. Check off subtasks with a
  `report:` line as each one lands.
- Be token-efficient: do not re-read files you have already read this session.

## Do not touch
- `bin/*.js` and `CODEMAP.md` are build output. Edit `src/` and regenerate.
```

--------------------------------

### Install Kandown with other package managers

Source: https://kandown.dev/docs/installation.md

Install Kandown globally using pnpm, yarn, or bun.

```bash
pnpm add -g kandown
```

```bash
yarn global add kandown
```

```bash
bun add -g kandown
```

--------------------------------

### Verify Kandown installation

Source: https://kandown.dev/docs/installation.md

Check the installed version and run the doctor command to diagnose issues.

```bash
kandown --version
```

```bash
kandown doctor
```

--------------------------------

### List and use workflows

Source: https://kandown.dev

Planned interface for listing and using workflows. Shows the default workflow and an example custom workflow, then sets the active workflow for the project.

```bash
kandown workflow list default · plan, one task, subtask reports ai-dev-tasks · PRD, then tasks, one at a time tdd · red, green, refactor, per subtask $ kandown workflow use ai-dev-tasks Workflow set for this project. # Instructions come from the CLI, never a file# in your repo that can drift out of date.
```

--------------------------------

### Start a session with board context

Source: https://kandown.dev/docs/agents/mcp.md

Provides the board context (rules, project instructions, and digest) that tells an agent what to act on. Use it before acting on the board, regardless of transport.

```bash
kandown work
```

--------------------------------

### Check Node.js version

Source: https://kandown.dev/docs/installation.md

Verify that Node.js 18 or newer is installed before using Kandown.

```bash
node --version
```

--------------------------------

### Run the MCP server

Source: https://kandown.dev/docs/agents/mcp.md

Starts the Kandown MCP server over stdio. It is meant to be launched by a client, not run in a terminal by hand, and operates on the Kandown project of its working directory.

```bash
kandown mcp
```

--------------------------------

### Manage the kandown daemon (status, start, stop, projects)

Source: https://kandown.dev/docs/guides/board-and-views.md

Commands to inspect and control the per-project daemon that serves the web board. The daemon outlives the terminal UI, so closing your shell does not close your browser tab. It binds to 127.0.0.1 only and mints a random per-project API token at startup.

```bash
kandown daemon status
kandown daemon start
kandown daemon stop
kandown projects        # every open kandown project on this machine
```

--------------------------------

### Run Kandown without installing via npx

Source: https://kandown.dev/docs/installation.md

Use npx to run Kandown directly for trying it out or one-off CI commands.

```bash
npx kandown init
```

```bash
npx kandown list --json
```

--------------------------------

### Launch Claude Code in a loop with kandown work

Source: https://kandown.dev/docs/agents/launching.md

Drive an agent from a script without the board UI. Uses 'kandown work' to get context and 'kandown list --json' to find the next Todo task. Task commands never touch the network and stdout is data-only, so command substitution captures exactly what you expect.

```bash
#!/usr/bin/env bash
set -euo pipefail

CONTEXT=$(kandown work)
NEXT=$(kandown list --json | jq -r '[.[] | select(.status=="Todo")][0].id // empty')

[ -z "$NEXT" ] && { echo "nothing actionable" >&2; exit 0; }

kandown move "$NEXT" "In progress"
claude -p "$CONTEXT

Work on task $NEXT. Update the task file as you go."

```

--------------------------------

### Create task with kandown create

Source: https://kandown.dev/docs/guides/tasks.md

Create a task from the CLI with priority, tags, assignee, and target column. The command prints only the new id on stdout, so $(…) captures exactly one value; add --json to get the whole task object back.

```bash
kandown create "Refactor auth middleware" \
  --priority P1 \
  --tag backend --tag security \
  --assignee chacha \
  --to "In progress"
```

--------------------------------

### kandown workflow subcommands

Source: https://kandown.dev/docs/reference/cli.md

Lists workflow subcommands for listing, showing, templating, using, validating, packing, and importing workflows. Store access is explicit through workflow store, install, and update.

```bash
kandown workflow list
kandown workflow show kandown-standard
kandown workflow template kandown-standard [template-id]
kandown workflow use diagnose-and-fix
kandown workflow validate ./my-workflow
kandown workflow pack ./my-workflow --output my-workflow.kandown-workflow.md
kandown workflow import ./my-workflow.kandown-workflow.md
```

--------------------------------

### Commit message example: feat(board): add group-by epic

Source: https://kandown.dev/docs/project/contributing.md

Example commit message following Conventional Commits: imperative mood, subject wrapped at 72 characters, and a body explaining why. Use types like feat, fix, chore, refactor, perf, style, docs, test, build, ci, revert; breaking changes go in a BREAKING CHANGE: footer.

```text
feat(board): add group-by epic

The backlog grew past the point where priority grouping was useful.
Epics were already in the data model but had no view.
```

--------------------------------

### kandown move command syntax and archive example

Source: https://kandown.dev/docs/reference/cli.md

Moves a task to a status column or to archived. Moving to the terminal column fails with non-zero exit code if any depends_on entry is unresolved.

```bash
kandown move <id> <status>
kandown move t14 archived     # archive
```

--------------------------------

### Open web board

Source: https://kandown.dev

Launch the web board interface.

```bash
kandown
```

--------------------------------

### Initialize a Kandown project with kandown init

Source: https://kandown.dev/docs/quick-start.md

Initializes a Kandown project in the current directory. Creates the tasks/ and .kandown/ folders and appends a single line to AGENTS.md or CLAUDE.md pointing agents at 'kandown work'.

```bash
cd my-project
kandown init
```

--------------------------------

### Create a task with kandown create

Source: https://kandown.dev/docs/quick-start.md

Creates a task from the command line with priority, tag, and assignee. Prints only the new task's id on stdout so it can be captured.

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

--------------------------------

### File tree: .kandown/kandown_work.md

Source: https://kandown.dev/docs/agents/instructions.md

Shows the expected location of the project-specific instructions file. The file is optional, empty by default, and its content is inserted after global instructions and before the final task or board context.

```text
.kandown/
└── kandown_work.md
```

--------------------------------

### Create and move a task with kandown create and kandown move

Source: https://kandown.dev/docs/quick-start.md

Creates a task, captures its id, and moves it to 'In progress' in one workflow. The id is printed on stdout by 'kandown create'.

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

--------------------------------

### Quick-add task syntax

Source: https://kandown.dev/docs/guides/tasks.md

Use this one-line syntax in the web board or terminal UI to create a task quickly. Kandown parses priority (p1-p4), tags (#tag), assignee (@name), and due date (due:friday or due:2026-08-01) from the text; everything else becomes the title.

```text
Fix login p1 #backend #security @chacha due:friday
```

--------------------------------

### Refresh daemons for all projects

Source: https://kandown.dev/docs/installation.md

Bring daemons of several open projects onto the current version in one go.

```bash
kandown daemon refresh-all
```

--------------------------------

### Launch the terminal board with kandown board

Source: https://kandown.dev/docs/guides/terminal-ui.md

Launches the keyboard-driven kanban board in the terminal. It is a peer of the web UI, using the same files and dependency gate, and works over SSH without a browser.

```bash
kandown board
```

--------------------------------

### kandown create command with flags

Source: https://kandown.dev/docs/reference/cli.md

Creates a task with optional priority, assignee, tags, target column, custom id, and JSON output. Defaults to the first column if --to is not specified.

```bash
kandown create "title" [-p priority] [-a assignee] [-t tag …] [--to status] [--id custom-id] [--json]
```

--------------------------------

### Quick-add task syntax

Source: https://kandown.dev/docs/quick-start.md

Quick-add syntax parsed by the web board's quick-add box. Encodes priority, tag, assignee, and due date in one line.

```text
Fix login p1 #backend @chacha due:friday
```

--------------------------------

### List tasks as JSON

Source: https://kandown.dev

List tasks as JSON, suitable for scripting and automation.

```bash
kandown list --json
```

--------------------------------

### Define a custom theme in JSON

Source: https://kandown.dev/docs/guides/appearance.md

A theme is a JSON object of design tokens. Paste this into Settings → Appearance → Custom theme; it is stored in .kandown/kandown.json and travels with the project.

```json
{
  "name": "My theme",
  "colors": {
    "bg": "#0c1d17",
    "surface": "#142a22",
    "border": "#1e372e",
    "text": "#e8f0ea",
    "textMuted": "#96a89e",
    "accent": "#88e138"
  }
}
```

--------------------------------

### Update Kandown on demand

Source: https://kandown.dev/docs/installation.md

Refresh the CLI and the bundled kandown.html in the current project.

```bash
kandown update
```

--------------------------------

### Script task operations with kandown list, create, move, commit

Source: https://kandown.dev/docs/agents/overview.md

Shows the stdout data-only contract: piping JSON to jq, capturing an ID from create, moving a task, and committing. Exit code 0 on success, non-zero on failure.

```bash
kandown list --json | jq '.[] | select(.priority=="P1")'

ID=$(kandown create "Refactor auth middleware" -p P1 -t backend)
kandown move "$ID" "In progress"

kandown commit -m "tasks: add auth refactor"
```

--------------------------------

### Open the terminal settings editor with kandown settings

Source: https://kandown.dev/docs/guides/terminal-ui.md

Opens a terminal settings editor covering the same configuration as the web Settings page: columns, theme, notifications, agents, and the 'kandown work' output.

```bash
kandown settings
```

--------------------------------

### kandown list command with flags

Source: https://kandown.dev/docs/reference/cli.md

Lists tasks with optional filters for status, assignee, tag, priority, archived, and JSON output. Use --json to emit JSON instead of a table.

```bash
kandown list [-s status] [-a assignee] [-t tag] [-p priority] [--archived] [--json]
```

--------------------------------

### Register the MCP server with Claude Code

Source: https://kandown.dev/docs/agents/mcp.md

Adds the Kandown MCP server to Claude Code. The command is always `kandown` with the single argument `mcp`, launched from your project directory.

```bash
claude mcp add kandown -- kandown mcp
```

--------------------------------

### Kandown folder layout

Source: https://kandown.dev/docs/reference/data-model.md

Shows the required folder layout for a Kandown project. The tasks/ directory is the source of truth; archived tasks live in tasks/archive/ and remain readable and in git. The .kandown/ directory holds configuration, the web app, optional agent instructions, workflow and skill packages, and daemon.json (runtime state plus API token, gitignored).

```text
tasks/                # the source of truth
├── t1.md
├── t14.md
└── archive/          # archived tasks, still readable and in git
    └── t3.md

.kandown/
├── kandown.json      # columns, theme, notifications, agents
├── kandown.html      # the web app, one self-contained file
├── kandown_work.md   # optional project agent instructions
├── workflows/        # optional local workflow packages
├── skills/           # optional local Markdown skill packages
└── daemon.json       # runtime state + API token (gitignored)
```

--------------------------------

### Subtasks checklist with report line

Source: https://kandown.dev/docs/reference/data-model.md

Shows the ## Subtasks checklist convention. Each item may carry an indented description and a report: line; report: is the field that turns a completed task into a work log, and agents are expected to fill it in as they go.

```markdown
## Subtasks
- [x] Extract the token parser
  The old middleware parsed tokens inline, which made it untestable.
  report: Moved to src/auth/token.ts, added unit tests for expiry.
- [ ] Cover the refresh path with tests
```

--------------------------------

### Forward the web daemon port over SSH

Source: https://kandown.dev/docs/guides/terminal-ui.md

Forwards the local port 5176 to the remote server so you can reach the optional web daemon from your laptop while using the TUI over SSH. Toggle the daemon with the 'd' key.

```bash
ssh -L 5176:localhost:5176 you@server
```

--------------------------------

### Archive task with kandown move

Source: https://kandown.dev/docs/guides/tasks.md

Archive a task by moving it to tasks/archive/. Archived tasks stay readable, greppable, and in git, but leave the active board.

```bash
kandown move t14 archived
```

--------------------------------

### kandown work with task id

Source: https://kandown.dev/docs/reference/cli.md

Prints the full agent context as Markdown on stdout. Passing a task id replaces the board digest with focused task context.

```bash
kandown work t42
```

--------------------------------

### Subtasks checklist with report lines

Source: https://kandown.dev/docs/guides/tasks.md

Define subtasks as a Markdown checklist under a ## Subtasks heading. Indented prose under a step adds context, and report: lines record what happened when the step was completed, turning a finished task into a work log.

```markdown
## Subtasks
- [x] Extract the token parser
  report: Moved to src/auth/token.ts, added unit tests for expiry.
- [ ] Cover the refresh path with tests
- [ ] Delete the legacy middleware
```

--------------------------------

### Uninstall Kandown globally

Source: https://kandown.dev/docs/installation.md

Remove the Kandown CLI globally with npm. Your tasks/ folder and .kandown/ config remain untouched.

```bash
npm uninstall -g kandown
```

--------------------------------

### Configure agent hook with KANDOWN_AGENT_HOOK_URL

Source: https://kandown.dev/docs/agents/launching.md

Configure the agent hook endpoint, label, and headers. The hook is triggered by pressing 'g' in the terminal UI or using 'Send to Agent' in the web board. It makes an outbound network request only when triggered, so point it to a trusted endpoint.

```bash
export KANDOWN_AGENT_HOOK_URL="https://example.internal/agents/kandown"
export KANDOWN_AGENT_HOOK_LABEL="Send to Orchestrator"
export KANDOWN_AGENT_HOOK_HEADERS='{"Authorization":"Bearer $TOKEN"}'

```

--------------------------------

### Commit tasks with kandown commit

Source: https://kandown.dev/docs/quick-start.md

Stages tasks/ and .kandown/kandown.json and commits them with the given message. Plain 'git add' works as well; this is a convenience, not a requirement.

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

--------------------------------

### kandown list with JSON filter for P1 tasks

Source: https://kandown.dev/docs/reference/cli.md

Pipes the JSON output of kandown list into jq to select tasks with priority P1 and print their titles.

```bash
kandown list --json | jq '.[] | select(.priority=="P1") | .title'
```

--------------------------------

### kandown create capturing ID in shell variable

Source: https://kandown.dev/docs/reference/cli.md

Creates a task with priority P1 and two tags, capturing the generated ID into the ID variable for later use.

```bash
ID=$(kandown create "Refactor auth middleware" -p P1 -t backend -t security)
```

--------------------------------

### Stop the Kandown daemon with kandown daemon stop

Source: https://kandown.dev/docs/quick-start.md

Stops the Kandown daemon from the terminal. Use this instead of quitting the TUI if you want to stop the background process.

```bash
kandown daemon stop
```

--------------------------------

### Task dependencies with depends_on

Source: https://kandown.dev/docs/guides/tasks.md

Declare task dependencies in the task file. A task with unresolved dependencies cannot be moved to the terminal column; the refusal is enforced identically in the browser, terminal UI, and CLI, and blocked tasks are annotated in the board digest agents read.

```yaml
depends_on: [t7, t12]
```

--------------------------------

### Disable automatic updates with KANDOWN_NO_UPDATE

Source: https://kandown.dev/docs/installation.md

Set the environment variable to turn off the automatic update check completely.

```bash
export KANDOWN_NO_UPDATE=1
```
Tokens:
Raw