Obsidian Kanban

Obsidian Kanban

Save tasks from Claude and Codex to a visual Kanban board — kept as plain Markdown in your Obsidian vault.

Tell the Claude app or the Codex app “add to kanban: renew the car insurance by Nov 30” — the card appears on your board
and as a - [ ] line in your notes. Drag it in the browser, tick it in Obsidian: both stay in sync.

From Claude & Codex · Quick start · Connect your AI · Screenshots · How it works · FAQ · Docs

_{Demo data. The chat panel is drawn; the board and the new card are real — the card also became line 19 of Tasks/Personal.md. Real screenshots of the Claude and Codex apps are just below.}

Save tasks from Claude and Codex

Ask your AI app in plain words. Moments later the task is a card on your board and a - [ ] line in your Obsidian note — no copying, no switching apps. Both apps reach the board through the MCP server that comes with it (setup).

_{Real screenshots of the Claude desktop app (Claude Code in its Code tab; it answered in its user's language, Russian) and the Codex app, both connected to a demo board. The titles, the arrows and the purple outline around each new card were added on top.}

Why Obsidian Kanban

• 📝 Your tasks stay plain Markdown. Cards are ordinary - [ ] lines in your Obsidian notes. No new format, no account, nothing to import or export.
• 👀 See everything at a glance. Columns, priorities, colors, due dates, checklists and comments — a board instead of a long list.
• 🤖 Your AI apps keep the board up to date. Ask the Claude app, Claude Code or the Codex app to add a task, move it, comment on it or close it. When it is unclear which board you mean, the assistant asks one short question instead of guessing.
• 🏠 Runs on your own computer. The board is a small web app on localhost. Your tasks do not leave your machine unless you decide to publish the board.

A closer look

Board. Drag cards between columns; tick a card to move it to Done. Categories, priorities, due dates and reminders at a glance.	Table. A spreadsheet view with inline editing, sorting and filters like status:Done priority:high.
Card details. Description, checklist with progress, links, comments (your assistant can leave them too), reminders — and the Markdown line the card lives on.	Dark mode. Follows your system theme, or pick one in the toolbar.

Quick start

Pick the way that suits you. Each ends with the board open at http://localhost:4000.

1. Let Claude Code install it (Mac, ~10 minutes)

Open Claude Code on your Mac and paste:

Install Obsidian Kanban on this Mac by following
https://github.com/sergi039/obsidian-kanban-app/blob/main/docs/personal-install.md

Claude asks which Obsidian vault to use and does the rest with one script: no administrator password, everything stays in your home folder. Afterwards, in a new Claude Code session, type “add to kanban: check the install” and watch the card appear. Details: docs/personal-install.md (Apple Silicon Mac).

2. Run it yourself (any computer with Node.js)

You need Node.js 22 and pnpm.

git clone https://github.com/sergi039/obsidian-kanban-app.git
cd obsidian-kanban-app
pnpm install

Create config.boards.json next to package.json and point it at your vault and a task file:

{
  "vaultRoot": "/path/to/your/Obsidian/Vault",
  "boards": [
    { "id": "personal", "name": "Personal", "file": "Tasks/Personal.md",
      "columns": ["Backlog", "This week", "In progress", "Done"] }
  ],
  "defaultColumns": ["Backlog", "In progress", "Done"]
}

pnpm build
SERVE_STATIC=1 pnpm --filter @kanban/api start

The task file is any note with checkboxes:

- [ ] ⏫ Renew passport before the summer trip
    - Book an appointment online
- [ ] Plan the Lisbon weekend
- [x] Pay the electricity bill

⏫ marks a high priority, indented lines become sub-items, - [x] is done.

3. Docker

Put the same config.boards.json into a config/ folder next to docker-compose.yml, then run VAULT_PATH=/path/to/vault docker compose up -d and open http://localhost:4000. Details: reference.

Connect your AI assistant

The app includes an MCP server — the standard way AI apps use tools. With it your assistant can list your boards, find cards, add a task, add to a card, move or close it, comment on it and follow up an email. It talks only to your local board, never directly to your files.

After the one-script install there is nothing to do: it registers the server for Claude Code, and for Codex when Codex is on the Mac.

Otherwise, step 1. Build the MCP server (the board must be running, see above):

pnpm --filter @kanban/mcp build

Step 2. Add it to your assistant (replace the path):

claude mcp add --scope user obsidian-kanban -e KANBAN_API_URL=http://127.0.0.1:4000 \
  -- node /path/to/obsidian-kanban-app/apps/mcp/dist/server.js

codex mcp add obsidian-kanban --env KANBAN_API_URL=http://127.0.0.1:4000 \
  -- node /path/to/obsidian-kanban-app/apps/mcp/dist/server.js

{
  "mcpServers": {
    "obsidian-kanban": {
      "command": "/absolute/path/to/node",
      "args": ["/path/to/obsidian-kanban-app/apps/mcp/dist/server.js"],
      "env": { "KANBAN_API_URL": "http://127.0.0.1:4000" }
    }
  }
}

If the board runs with API_TOKEN, add KANBAN_API_TOKEN with the same value. Card links in the answers open KANBAN_APP_URL when you set it (your board's public address), else KANBAN_API_URL.

Step 3. Ask in plain words:

More: docs/desktop-mcp.md — the tools, tasks from email, a board on another Mac, the safety model.

How it works

• Obsidian stays the source. Each task line in your note is a card; ticking [x] in Obsidian moves it to Done, and dragging it back on the board unticks it.
• Changes show up in under a second. A file watcher picks up edits in Obsidian; edits on the board are written back to the file. Every open tab updates live.
• Nothing gets lost. The card's column is kept in an invisible comment on its line (<!-- kb:id=… kb:col=… -->, an HTML comment that Obsidian's reading view hides), so the board survives even if its database is deleted.
• Extras live next to the app. Checklists, comments, categories and reminders are stored in a local SQLite file, not in your notes.

Features

• Views — board with drag & drop, table with inline editing, saved views, filters and sorting
• Cards — #1-style IDs, descriptions, checklists, links, comments, due dates, custom fields
• Organize — priorities, colored categories, collapsible columns, bulk move and close, trash with restore
• Remind — in-app and browser reminders; macOS notifications, Calendar and Mail through a small local agent (reminders)
• Calendars — Outlook and Google events linked to a card show up on it
• Automate — rules such as “when a card moves to Done, set a field”
• Stay safe — runs on localhost, refuses requests from other web pages, backs up its config and database on every start

_{The full list is in the reference.}

FAQ

Documentation

Contributing

Issues and pull requests are welcome. pnpm test runs the test suites; the reference shows the development setup with hot reload.

License

MIT. Obsidian Kanban is an independent project, not affiliated with Obsidian, Anthropic or OpenAI; their names are trademarks of their owners.