@cwim/kanban 1.1.5 → 1.1.6

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,138 @@ Add CWIM Kanban to your Claude Code MCP configuration:
 }
 ```
 
-Once connected, Claude can use these tools during your sessions:
-
-| 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 |
-
-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.
-
-## Session Management
+## Memory Features
 
-CWIM Kanban supports **full session isolation** — each Claude Code project gets its own Kanban board:
+### Smart Context Recall
 
-- 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
+Before starting complex work, Claude can recall relevant past tasks:
 
-### Switching Sessions
-
-**Dashboard:** Click the session name in the header center to open the dropdown selector.
-
-**CLI:**
-```bash
-# List all available sessions
-kanban sessions
-
-# Switch to a different session
-kanban switch my-project
-```
-
-**MCP:**
 ```
-session_list    # Show available sessions
-session_switch  # Change active session
+task_recall({ context: "refactoring auth middleware" })
 ```
 
-## CLI Commands
-
-### `kanban` (default) — Launch Dashboard
+Returns the most relevant tasks based on keyword matching, recency, and status. No more "what were we doing again?"
 
-```bash
-# Start dashboard server and open browser
-kanban
+### Append Notes Without Overwriting
 
-# Custom port
-kanban --port 8080
+Build context over time without losing previous work:
 
-# 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_append_note({
+  id: "tf-abc123",
+  note: "Discovered edge case with JWT refresh tokens"
+})
 ```
 
-### `kanban sessions` — List Sessions
-
-```bash
-# Show all available sessions with active indicator
-kanban sessions
-```
+Each note is timestamped and preserved. The task grows smarter as you work.
 
-### `kanban switch` — Change Session
+### Session Isolation
 
-```bash
-# Switch to a specific session
-kanban switch my-project
-```
+Each Claude Code project gets its own memory space. Work on multiple projects without context bleeding:
 
-### `kanban add` — Create Task
+- Auto-detected from `~/.claude/projects/`
+- Switch between sessions via dashboard, CLI, or MCP
+- "Independent Mode" for non-Claude work
 
-```bash
-# Simple task
-kanban add "Fix auth middleware"
+### Keyword Search
 
-# With description and tags
-kanban add "Refactor database layer" -d "Extract connection pooling" -t refactor,db
+Find anything instantly across your entire task history:
 
-# Direct to a column
-kanban add "Write tests" -s in-progress
+```
+task_list({ query: "auth" })
 ```
 
-### `kanban list` — List Tasks
-
-```bash
-# All tasks in current session
-kanban list
+## Visual Dashboard
 
-# Filter by status
-kanban list --status done
+While your AI works in the background, watch progress in real time:
 
-# Filter by tag
-kanban list --tag refactor
-```
+- **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
 
-### `kanban done` — Mark Complete
+## MCP Tools
 
-```bash
-kanban done tf-abc123
-```
+| 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 |
 
-### `kanban move` — Change Status
+## CLI Commands
 
+### Launch Dashboard
 ```bash
-# Move to any column
-kanban move tf-abc123 blocked
-kanban move tf-abc123 in-progress
+kanban                    # Start dashboard and open browser
+kanban --port 8080        # Custom port
+kanban --no-open          # Don't auto-open browser
 ```
 
-### `kanban status` — Board Overview
-
+### Memory Operations
 ```bash
-# Quick summary of all columns
-kanban status
+kanban recall "auth"      # Recall relevant tasks
+kanban note tf-abc123 "Edge case found"  # Append note
 ```
 
-### `kanban show` — Task Details
-
+### 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` — Delete Task
-
-```bash
 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.6",
   "description": "Minimal Kanban task tracking with MCP integration for Claude Code",
   "type": "module",
   "main": "dist/index.js",