@cwim/kanban 1.1.5 → 1.1.7

package/README.md

@@ -1,17 +1,28 @@
 # CWIM Kanban
 
-> Minimal Kanban task tracking with MCP integration for Claude Code. Local-first, zero-config, and purpose-built for long-running AI-assisted workflows.
+> Your AI's long-term memory. Visualized.
 
-## Overview
+Stop losing context between Claude sessions. CWIM Kanban gives your AI assistant a persistent memory layer with a beautiful dashboard to watch it work.
 
-CWIM Kanban is a complementary package to CWIM (Context Window Intelligence Manager) that adds visual task tracking to your Claude Code sessions. It consists of:
+## The Problem
 
-- **MCP Server** — Exposes Kanban operations as Claude Code tools (`task_create`, `task_move`, `task_list`, etc.)
-- **Web Dashboard** — A clean, dark-themed Kanban board served locally at `http://localhost:3456`
-- **CLI** — Full command-line interface for managing tasks outside of Claude
-- **Local JSON Storage** — Per-session task storage in `~/.kanban/sessions/`, no cloud or database needed
+Ever ask Claude to "continue where we left off" and get a blank stare? That's because Claude has no memory between sessions. Every conversation starts fresh, and complex multi-step work gets lost.
 
-As Claude works through complex multi-step tasks, it can create cards, move them across columns, and you watch progress unfold in real time on the board.
+CWIM Kanban fixes this by giving Claude a persistent task memory that survives across sessions.
+
+## How It Works
+
+```
+User: "Continue the auth refactor"
+    |
+Claude: task_recall("auth refactor")
+    |
+Memory: "Found: [in-progress] Refactor auth middleware"
+    |
+Claude: "Ah yes, we were extracting JWT validation..."
+```
+
+As Claude works through complex tasks, it creates cards, appends notes, and moves them across columns. You watch progress unfold in real time on the board. When you return tomorrow, Claude recalls exactly where you left off.
 
 ## Installation
 
@@ -26,12 +37,13 @@ npx @cwim/kanban
 kanban
 ```
 
-## Claude Code Integration (MCP)
-
-Add CWIM Kanban to your Claude Code MCP configuration:
+## Quick Start
 
 ```bash
-# Add to your Claude Code config (e.g., ~/.claude/config.json)
+# Start the dashboard
+kanban
+
+# Add to your Claude Code MCP config (~/.claude/config.json)
 {
   "mcpServers": {
     "kanban": {
@@ -42,257 +54,192 @@ Add CWIM Kanban to your Claude Code MCP configuration:
 }
 ```
 
-Once connected, Claude can use these tools during your sessions:
+## Making Claude Use It
 
-| Tool | Purpose |
-|------|---------|
-| `task_create` | Create a new task card |
-| `task_update` | Edit task title, description, tags |
-| `task_move` | Move a task to another column |
-| `task_delete` | Remove a task |
-| `task_list` | List all tasks in current session (optionally filtered) |
-| `task_get` | Show details of a specific task |
-| `session_list` | List all available sessions |
-| `session_switch` | Switch to a different session |
+Just installing the MCP isn't enough — Claude needs instructions to use it.
 
-Claude will automatically detect the tools and use them to track progress on complex tasks. Tasks created via MCP are tagged with source "claude" so you can distinguish them from manually created ones.
+Add a `CLAUDE.md` file to your project root:
 
-## Session Management
+```markdown
+## Task Tracking
+Use the cwim-kanban MCP to track all work in this project.
 
-CWIM Kanban supports **full session isolation** — each Claude Code project gets its own Kanban board:
+### Workflow
+1. **Before starting**: Call `task_recall` with what you're about to work on
+2. **Starting a task**: Create or move to `in-progress`
+3. **Making progress**: Append notes with discoveries, decisions, or blockers
+4. **Finishing**: Move to `done` and append a summary note
+5. **Blocked**: Move to `blocked` with a note explaining why
 
-- Sessions are auto-detected from `~/.claude/projects/`
-- Each session has isolated task storage
-- Switch between sessions via dashboard dropdown, CLI, or MCP
-- "Independent Mode" available when no Claude session is active
+### Example
+```
+// Check if we have existing context
+task_recall({ context: "refactoring auth middleware" })
 
-### Switching Sessions
+// Create or update task
+task_create({
+  title: "Refactor auth middleware",
+  description: "Extract JWT validation into separate module",
+  status: "in-progress",
+  tags: ["refactor", "auth"]
+})
 
-**Dashboard:** Click the session name in the header center to open the dropdown selector.
+// Append progress notes
+task_append_note({
+  id: "tf-abc123",
+  note: "Discovered edge case with refresh tokens"
+})
 
-**CLI:**
-```bash
-# List all available sessions
-kanban sessions
-
-# Switch to a different session
-kanban switch my-project
+// Mark complete
+task_move({ id: "tf-abc123", status: "done" })
+task_append_note({
+  id: "tf-abc123",
+  note: "Completed: Extracted JWT validation, all tests passing"
+})
 ```
 
-**MCP:**
-```
-session_list    # Show available sessions
-session_switch  # Change active session
+### Rules
+- Always check for existing tasks before creating new ones
+- Use tags consistently (e.g., "bug", "feature", "refactor", "docs")
+- Append notes liberally - they build context for future sessions
+- Move tasks to "blocked" immediately when stuck, with explanation
+- Keep task titles concise but descriptive
 ```
 
-## CLI Commands
+This makes the behavior automatic — no need to ask Claude every session.
 
-### `kanban` (default) — Launch Dashboard
+## Memory Features
 
-```bash
-# Start dashboard server and open browser
-kanban
+### Smart Context Recall
 
-# Custom port
-kanban --port 8080
+Before starting complex work, Claude can recall relevant past tasks:
 
-# Don't auto-open browser
-kanban --no-open
 ```
-
-### `kanban mcp` — Start MCP Server
-
-```bash
-# Run in MCP mode (stdio transport for Claude Code)
-kanban mcp
+task_recall({ context: "refactoring auth middleware" })
 ```
 
-### `kanban sessions` — List Sessions
+Returns the most relevant tasks based on keyword matching, recency, and status. No more "what were we doing again?"
 
-```bash
-# Show all available sessions with active indicator
-kanban sessions
-```
+### Append Notes Without Overwriting
 
-### `kanban switch` — Change Session
+Build context over time without losing previous work:
 
-```bash
-# Switch to a specific session
-kanban switch my-project
+```
+task_append_note({
+  id: "tf-abc123",
+  note: "Discovered edge case with JWT refresh tokens"
+})
 ```
 
-### `kanban add` — Create Task
+Each note is timestamped and preserved. The task grows smarter as you work.
 
-```bash
-# Simple task
-kanban add "Fix auth middleware"
+### Session Isolation
 
-# With description and tags
-kanban add "Refactor database layer" -d "Extract connection pooling" -t refactor,db
+Each Claude Code project gets its own memory space. Work on multiple projects without context bleeding:
 
-# Direct to a column
-kanban add "Write tests" -s in-progress
-```
+- Auto-detected from `~/.claude/projects/`
+- Switch between sessions via dashboard, CLI, or MCP
+- "Independent Mode" for non-Claude work
 
-### `kanban list` — List Tasks
+### Keyword Search
 
-```bash
-# All tasks in current session
-kanban list
-
-# Filter by status
-kanban list --status done
+Find anything instantly across your entire task history:
 
-# Filter by tag
-kanban list --tag refactor
+```
+task_list({ query: "auth" })
 ```
 
-### `kanban done` — Mark Complete
+## Visual Dashboard
 
-```bash
-kanban done tf-abc123
-```
+While your AI works in the background, watch progress in real time:
 
-### `kanban move` — Change Status
+- **Real-time updates** - Board refreshes every 2 seconds
+- **4 columns** - To Do, In Progress, Done, Blocked
+- **Session switching** - Dropdown to browse projects
+- **Tag support** - Categorize tasks with badges
+- **Source tracking** - Distinguish AI-created vs manual tasks
+- **Keyboard shortcuts** - `r` to refresh, `1-4` to filter columns
 
-```bash
-# Move to any column
-kanban move tf-abc123 blocked
-kanban move tf-abc123 in-progress
-```
+## MCP Tools
 
-### `kanban status` — Board Overview
+| Tool | Purpose |
+|------|---------|
+| `task_recall` | Intelligently recall relevant task context |
+| `task_create` | Create a new task card |
+| `task_append_note` | Append timestamped note to a task |
+| `task_update` | Edit task title, description, tags |
+| `task_move` | Move a task to another column |
+| `task_delete` | Remove a task |
+| `task_list` | List tasks (optionally filtered/search) |
+| `task_get` | Show details of a specific task |
+| `session_list` | List all available sessions |
+| `session_switch` | Switch to a different session |
 
+## CLI Commands
+
+### Launch Dashboard
 ```bash
-# Quick summary of all columns
-kanban status
+kanban                    # Start dashboard and open browser
+kanban --port 8080        # Custom port
+kanban --no-open          # Don't auto-open browser
 ```
 
-### `kanban show` — Task Details
-
+### Memory Operations
 ```bash
-kanban show tf-abc123
+kanban recall "auth"      # Recall relevant tasks
+kanban note tf-abc123 "Edge case found"  # Append note
 ```
 
-### `kanban remove` — Delete Task
-
+### Task Management
 ```bash
+kanban add "Fix auth" -d "JWT validation" -t bug,auth
+kanban list --query "auth"
+kanban move tf-abc123 done
+kanban show tf-abc123
 kanban remove tf-abc123
 ```
 
-### `kanban init` — Initialize Storage
-
+### Session Management
 ```bash
-# Creates ~/.kanban/ directory structure
-kanban init
+kanban sessions           # List all sessions
+kanban switch my-project  # Change active session
 ```
 
-## Dashboard Features
-
-- **Real-time updates** — Board refreshes every 2 seconds, showing changes as Claude moves tasks
-- **4 columns** — To Do, In Progress, Done, Blocked
-- **Visual indicators** — Color-coded borders, pulsing LIVE badge, flash animation on task moves
-- **Session switching** — Dropdown in header to browse and switch between Claude projects
-- **Session isolation** — Each project has its own independent task board
-- **Tag support** — Tasks show tags as badges for quick categorization
-- **Source tracking** — Distinguishes between Claude-created and manually-created tasks
-- **Keyboard shortcuts** — `r` to refresh, `1-4` to filter columns
-- **New task toast** — Brief notification when a new task appears
-
 ## Data Storage
 
-All data is stored locally in `~/.kanban/sessions/{session-name}/tasks.json`:
+All data stored locally in `~/.kanban/sessions/`:
 
 ```
 ~/.kanban/
 ├── sessions/
 │   ├── my-project/
 │   │   └── tasks.json
-│   ├── another-project/
-│   │   └── tasks.json
 │   └── independent/
 │       └── tasks.json
 └── active-session.json
 ```
 
-Each session's tasks.json:
-
-```json
-{
-  "version": 1,
-  "updatedAt": "2026-05-23T10:30:00Z",
-  "session": {
-    "name": "my-project",
-    "path": "/home/user/.claude/projects/my-project"
-  },
-  "tasks": [
-    {
-      "id": "tf-001",
-      "title": "Refactor auth middleware",
-      "description": "Extract JWT validation into separate module",
-      "status": "in-progress",
-      "tags": ["refactor", "auth"],
-      "source": "claude",
-      "createdAt": "2026-05-23T10:15:00Z",
-      "updatedAt": "2026-05-23T10:20:00Z"
-    }
-  ]
-}
-```
-
-- **Local-first** — No cloud services, no accounts, no network required
-- **Human-readable** — JSON format you can edit directly if needed
-- **Session-aware** — Each Claude Code project gets its own isolated board
-- **Portable** — Back up or version-control your `~/.kanban/` directory
-
-## Programmatic API
-
-Core functions are exported for custom integrations:
-
-```typescript
-import { createTask, listTasks, moveTask, getAllData, listAllSessions, setActiveSession } from '@cwim/kanban';
-
-// Create a task in current session
-const task = await createTask({
-  title: 'My task',
-  description: 'Optional details',
-  status: 'todo',
-  tags: ['api'],
-  source: 'manual'
-});
-
-// List all available sessions
-const sessions = await listAllSessions();
-
-// Switch active session
-await setActiveSession('my-project');
-
-// Get all data for current session
-const data = await getAllData();
-console.log(data.tasks);
-```
-
-See `src/index.ts` for all available exports.
+- **Local-first** - No cloud, no accounts, no network required
+- **Human-readable** - Plain JSON you can edit directly
+- **Portable** - Back up or version-control your `~/.kanban/` directory
 
 ## Architecture
 
 ```
 Claude Code → MCP Server (stdio) → session tasks.json ← HTTP Server ← Dashboard UI
-                ↑                                              ↑
-           task_create, move, etc.                    polling /api/tasks
-                                                        + /api/sessions
+                |                                              |
+           task_recall, append_note, etc.              polling /api/tasks
 ```
 
-- **MCP Server** and **HTTP Server** are separate processes
-- They communicate through per-session JSON files, not sockets or IPC
-- The dashboard polls `/api/tasks` and `/api/sessions` every 2 seconds
-- All mutations go through the MCP tools or CLI commands
-- Session switching is persisted in `~/.kanban/active-session.json`
+- MCP Server and HTTP Server are separate processes
+- They communicate through per-session JSON files
+- Dashboard polls for updates every 2 seconds
+- Session switching persisted in `~/.kanban/active-session.json`
 
 ## Requirements
 
 - Node.js 18+
-- Claude Code (optional — dashboard works independently)
+- Claude Code (optional - dashboard works independently)
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cwim/kanban",
-  "version": "1.1.5",
+  "version": "1.1.7",
   "description": "Minimal Kanban task tracking with MCP integration for Claude Code",
   "type": "module",
   "main": "dist/index.js",