claude-kanban
A project-first Obsidian workspace for Claude Code. Hooks track every session deterministically; a reconciler renders kanban boards, plans, designs, and spike folders into your vault. The plugin never depends on Claude remembering to log itself.
What this is
If you run many Claude Code sessions across many worktrees, this plugin keeps a live dashboard in Obsidian showing what each session is doing, organized by logical project (not by repo). Each project gets its own folder with:
README.md — project charterPlan.md — planning decisions (auto-appended via /claude-kanban:note plan)Design.md — design decisions (auto-appended via /claude-kanban:note design)Tasks.md — kanban: Backlog (user-authored) + Doing / Blocked / Done / Archive (reconciler-owned)Sessions.md — kanban: Active / Idle / Stale / Ended (reconciler-owned, auto-aged)Spikes/ — one note per investigation
A master _Index.md rolls all projects up with hot/warm/cold buckets.
How enforcement works
Claude Code's hook system runs shell scripts on session lifecycle events (SessionStart, SessionEnd, Stop, UserPromptSubmit). Those scripts append events to a log; a reconciler (run by launchd every ~10s) folds events into state and writes the vault.
The user (you) never has to ask Claude to log itself. If Claude crashes, refuses, or compacts away the instruction, the hook still fires — that's the whole point.
Install (local-only v1)
/plugin marketplace add ~/workspace/claude-kanban
/plugin install claude-kanban@claude-kanban
/claude-kanban:setup
setup interactively asks for your Obsidian vault path, writes ~/.claude/data/claude-kanban/config.json, and installs the LaunchAgent.
Requirements: bun, jq, macOS (uses launchd).
Project association
A session resolves to a project via three layers (highest precedence first):
- Slash command:
/claude-kanban:project <slug> — overrides for the rest of the session.
.claude-project file: drop a single-line file containing the slug at the worktree root (or any ancestor of the cwd). The SessionStart hook walks upward.worktree-map.json: ~/.claude/data/claude-kanban/worktree-map.json — a JSON object mapping absolute paths to slugs. User-maintained.
Unresolved → the session lands in _unassigned. Run /claude-kanban:project <slug> to reassign.
Projects must be registered before they can be assigned. Use /claude-kanban:project-new <slug> "<Display Name>".
Slash commands
| Command | Purpose |
|---|
/claude-kanban:setup | First-run wizard: vault path, data dir, LaunchAgent |
/claude-kanban:teardown [--purge-data] | Remove LaunchAgent; optionally remove plugin data. Vault is untouched. |
/claude-kanban:project <slug> | Assign current session to a registered project |
/claude-kanban:project-new <slug> "<name>" | Register a new project; scaffold folder from templates |
/claude-kanban:task <text> | Claim a Backlog task by exact text (creates one in Doing if no match) |
/claude-kanban:task-new <text> | Create a new task in Doing with this session attached |
/claude-kanban:task-done | Mark the claimed task Done |
/claude-kanban:task-block <reason> | Move the claimed task to Blocked |
/claude-kanban:note plan <body> | Append a paragraph to current project's Plan.md |
/claude-kanban:note design <body> | Append a paragraph to current project's Design.md |
/claude-kanban:spike <slug> | Create Spikes/YYYY-MM-DD-<slug>.md |
/claude-kanban:status | Show this session's project, claimed task, last activity |
How tasks and sessions interact
Tasks and sessions live on separate boards within each project:
Tasks.md — Backlog is where you (in Obsidian) drop tasks you might do later. Add lines like - [ ] Something I might do directly in the board view. The reconciler does not touch unclaimed Backlog items.Sessions.md — every Claude session in the project gets a card here. Columns are state, not workstreams: Active (≤5 min since last activity), Idle (≤2 hr), Stale (>2 hr), Ended (clean exit).- When a session runs
/claude-kanban:task <exact-text>, the reconciler moves that line from Backlog to Doing and attaches the session. The Backlog line disappears (it's now tracked); manual moves back to Backlog in Obsidian work as expected.
Authoring Plan / Design / README
You author these directly in Obsidian. The reconciler appends to Plan.md and Design.md via /claude-kanban:note (each entry timestamped with the session id; idempotent via a trailing HTML comment), but never overwrites your content. README.md is fully yours after the initial template seed.
Authoring Backlog tasks
