claude-code-kanban 4.12.0 → 4.13.0

package/README.md

@@ -8,9 +8,7 @@
 
 > Watch Claude Code work, in real time.
 
-![Dark mode](assets/screenshot-dark-v2.png)
-
-![Light mode](assets/screenshot-light-v2.png)
+![Kanban board with session log](assets/shot-session-log.png)
 
 ## Getting Started
 
@@ -22,11 +20,7 @@ Hooks enable subagent tracking, waiting-for-user detection, and session activity
 npx claude-code-kanban --install
 ```
 
-This will:
-- Copy `agent-spy.sh` to `~/.claude/hooks/` (requires `jq`)
-- Add `SubagentStart`, `SubagentStop`, `TeammateIdle`, and `PostToolUse` hooks to `~/.claude/settings.json`
-
-All changes are non-destructive — existing settings are preserved.
+Non-destructive — existing settings in `~/.claude/settings.json` are preserved. Uninstall anytime with `npx claude-code-kanban --uninstall`.
 
 ### 2. Start the dashboard
 
@@ -34,72 +28,34 @@ All changes are non-destructive — existing settings are preserved.
 npx claude-code-kanban --open
 ```
 
-Open http://localhost:3541 (or use `--open` to auto-launch the browser).
-
 ### 3. Use Claude Code as usual
 
-Tasks, agents, and messages appear on the board automatically. No changes to your Claude Code workflow needed.
-
-> To uninstall hooks: `npx claude-code-kanban --uninstall`
+Tasks, agents, and messages appear on the board automatically — Claude Code writes task files and conversation logs to `~/.claude`, the dashboard watches them and streams updates to the browser via SSE. It never directs Claude's work.
 
 ## Features
 
 - **Real-time Kanban board** — Tasks move through Pending → In Progress → Completed as Claude works
-- **Agent log** — Live subagent tracking (start/stop/idle) with prompts, duration, and status
-- **Session message log** — Browse recent messages, tool calls, and model info (`Shift+L`)
+- **Session log** — The full conversation timeline: prompts, replies, tool calls and results (`Shift+L`)
+- **Agent log** — Live subagent tracking with prompts, duration, status, and idle detection
+- **Task detail panel** — Full description, notes, blockedBy/blocks dependencies, inline editing
+- **Follow & pin** — Follow the latest message live (`Shift+M`), pin the messages that matter
+- **Tool stats & impact** — Per-session tool usage breakdown and file impact
 - **Waiting-for-user indicators** — Amber highlight on sessions needing permission or input
-- **Plan correlation** — Plan sessions linked to their implementation sessions
 - **Agent teams** — Color-coded team members, owner filtering, member count badges
-- **Task dependencies** — See blockedBy/blocks relationships and the critical path
-- **Live activity feed** — Stream of all in-progress tasks across every session
-- **Session management** — Fuzzy search, project/branch display, active/stale session styling
-- **Cleanup** — Delete tasks (with dependency checks) or bulk-delete entire sessions
-- **Keyboard shortcuts** — Press `?` for help; `Shift+M` for live message follow
-
-## Configuration
-
-```bash
-PORT=8080 npx claude-code-kanban        # Custom port
-npx claude-code-kanban --open            # Auto-open browser
-npx claude-code-kanban --dir=~/.claude-work  # Custom Claude config dir
-```
-
-If port 3541 is in use, the server falls back to a random available port.
-
-### Global install
-
-```bash
-npm install -g claude-code-kanban
-claude-code-kanban --open
-```
-
-## How It Works
+- **17 color themes** — Dracula, Nord, Catppuccin, Gruvbox, Tokyo Night, and more — each in light and dark
+- **Storage manager** — Inspect disk usage and clean up stale sessions and tasks
+- **Keyboard-first** — Press `?` for the full shortcut reference
 
-Claude Code writes task files to `~/.claude/tasks/` and conversation logs to `~/.claude/projects/`. The dashboard watches these directories with [chokidar](https://github.com/paulmillr/chokidar) and pushes updates to the browser via Server-Sent Events (SSE). Nothing is modified — the dashboard is read-only.
+![Session info](assets/shot-session-info.png)
 
-**Tasks** are picked up automatically from Claude Code's native task system (TodoWrite). No hooks needed.
+![Subagent preview](assets/shot-subagent-preview.png)
 
-**Hooks** extend observability beyond tasks. When installed, lightweight shell scripts fire on Claude Code lifecycle events and write JSON markers that the dashboard picks up:
+![Theme picker](assets/shot-theme-picker.png)
 
-| Hook event | What it enables |
-|------------|----------------|
-| `SubagentStart` / `SubagentStop` | Agent log — see subagent spawns, durations, prompts |
-| `TeammateIdle` | Idle detection for team member agents |
-| `PostToolUse` | Waiting-for-user detection (permission prompts, AskUserQuestion) |
 
 ## Context Window Monitoring
 
-Track real-time context window usage for each Claude Code session directly in the dashboard sidebar and detail panel.
-
-### Setup
-
-The installer copies `context-status.sh` alongside the agent hooks:
-
-```bash
-npx claude-code-kanban --install
-```
-
-Then add it to your statusline in `~/.claude/settings.json`:
+Per-session context usage bars, token/cost breakdowns, and model info in the sidebar and detail panel. The installer copies `context-status.sh` — wire it into your statusline in `~/.claude/settings.json`:
 
 ```json
 {
@@ -111,27 +67,17 @@ Then add it to your statusline in `~/.claude/settings.json`:
 }
 ```
 
-The script pipes through — your existing statusline still works. It just writes a snapshot to `~/.claude/context-status/{sessionId}.json` on each update.
-
-### What you get
+The script pipes through, so your existing statusline keeps working.
 
-- **Sidebar bar** — compact context usage bar per session with color thresholds (green → yellow → orange → red) and a 200K token marker
-- **Detail panel** — input/output token breakdown, cache read tokens, cost, duration, API time, lines added/removed, and model name
-- Only shown for active or pinned sessions
-
-## FAQ
-
-**Does this control Claude?**
-No. The viewer only observes — it never writes to task files or directs Claude's work.
-
-**Does it work with agent teams?**
-Yes. Team sessions are auto-detected with color-coded members and owner filtering.
+## Configuration
 
-**Does it require Claude Code to be running?**
-No. You can browse past sessions anytime. Live updates resume when Claude starts working again.
+```bash
+PORT=8080 npx claude-code-kanban             # Custom port (falls back if busy)
+npx claude-code-kanban --open                # Auto-open browser
+npx claude-code-kanban --dir=~/.claude-work  # Custom Claude config dir
+```
 
-**What happens without hooks?**
-The Kanban board still shows tasks, but you won't see the agent log, waiting-for-user indicators, or live session activity. Run `npx claude-code-kanban --install` for the full experience.
+Global install: `npm install -g claude-code-kanban`, then `claude-code-kanban --open`.
 
 ## License
 

package/lib/parsers.js

@@ -1029,14 +1029,15 @@ const CACHED_IMAGE_MIME = {
   png: 'image/png', jpg: 'image/jpeg', jpeg: 'image/jpeg', gif: 'image/gif', webp: 'image/webp',
 };
 
-// Serve pasted image N from ~/.claude/image-cache/<sessionId>/. The cached file may
+// Serve pasted image N from <claudeDir>/image-cache/<sessionId>/. The cached file may
 // be any image format, so resolve it by index rather than assuming .png. sessionId
 // is validated to a bare id to prevent path traversal.
-function readCachedImage(sessionId, n) {
+function readCachedImage(sessionId, n, claudeDir) {
   const idx = Number(n);
   if (!sessionId || !/^[A-Za-z0-9._-]+$/.test(sessionId)) return null;
   if (!Number.isInteger(idx) || idx < 0) return null;
-  const dir = path.join(require('os').homedir(), '.claude', 'image-cache', sessionId);
+  const baseDir = claudeDir || path.join(require('os').homedir(), '.claude');
+  const dir = path.join(baseDir, 'image-cache', sessionId);
   try {
     const match = readdirSync(dir).find((f) => {
       const dot = f.lastIndexOf('.');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-code-kanban",
-  "version": "4.12.0",
+  "version": "4.13.0",
   "description": "A web-based Kanban board for viewing Claude Code tasks with agent teams support",
   "main": "server.js",
   "bin": {

package/server.js

@@ -54,7 +54,7 @@ function getClaudeDir() {
       return dir.startsWith('~') ? dir.replace('~', os.homedir()) : dir;
     }
   }
-  return process.env.CLAUDE_DIR || path.join(os.homedir(), '.claude');
+  return process.env.CLAUDE_CONFIG_DIR || process.env.CLAUDE_DIR || path.join(os.homedir(), '.claude');
 }
 
 function getArgUrl(argName, envName) {
@@ -2110,7 +2110,7 @@ app.get('/api/sessions/:sessionId/tool-result-image/:toolUseId/:n', (req, res) =
 });
 
 app.get('/api/sessions/:sessionId/cached-image/:n', (req, res) => {
-  const img = readCachedImage(req.params.sessionId, req.params.n);
+  const img = readCachedImage(req.params.sessionId, req.params.n, CLAUDE_DIR);
   if (!img) return res.status(404).end();
   res.setHeader('Content-Type', img.mediaType);
   res.setHeader('Cache-Control', 'no-store');