claude-code-kanban 4.24.0 → 4.25.0

package/README.md

@@ -22,6 +22,8 @@ npx claude-code-kanban --install
 
 Non-destructive — existing settings in `~/.claude/settings.json` are preserved. Uninstall anytime with `npx claude-code-kanban --uninstall`.
 
+Using another Claude config dir? Pass `--dir=<path>` (or set `CLAUDE_CONFIG_DIR`) to both `--install` and `--uninstall`. The plugin, hooks and statusLine land in that dir, and the hooks write their data under it when Claude Code runs with the same `CLAUDE_CONFIG_DIR`.
+
 ### 2. Start the dashboard
 
 ```bash
@@ -84,7 +86,7 @@ The script pipes through, so your existing statusline keeps working.
 ```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
+npx claude-code-kanban --dir=~/.claude-work  # Custom Claude config dir (or CLAUDE_CONFIG_DIR)
 ```
 
 Global install: `npm install -g claude-code-kanban`, then `claude-code-kanban --open`.

package/cli.js

@@ -155,7 +155,7 @@ function printTopHelp() {
   console.log('  --version, -v         Print version and exit');
   console.log('\nServer mode (no subcommand):');
   console.log('  --port <n>            Port to listen on (default 3541)');
-  console.log('  --dir <path>          Override Claude config dir (default ~/.claude)');
+  console.log('  --dir <path>          Override Claude config dir (default ~/.claude); also targets --install/--uninstall');
   console.log('  --open                Open browser on start');
   console.log('  --install, --uninstall    Install or remove the plugin, context spy, and statusline');
   console.log('  --plugin-only         With --install: refresh only the plugin, skip context spy and statusline');

package/install.js

@@ -5,15 +5,19 @@ const path = require('path');
 const os = require('os');
 const readline = require('readline');
 const { execSync } = require('child_process');
+const { getClaudeDir, claudeCliEnv, displayPath } = require('./lib/claude-dir');
 
-const CLAUDE_DIR = path.join(os.homedir(), '.claude');
+const CLAUDE_DIR = getClaudeDir();
+const CLI_ENV = claudeCliEnv(CLAUDE_DIR);
 const CCK_DIR = path.join(CLAUDE_DIR, '.cck');
 const HOOKS_DIR = path.join(CLAUDE_DIR, 'hooks');
 const SETTINGS_PATH = path.join(CLAUDE_DIR, 'settings.json');
 const PLUGIN_SRC = path.join(__dirname, 'plugin');
 const PLUGIN_DEST = path.join(CCK_DIR, 'plugin');
-const CTX_SCRIPT_SRC = path.join(PLUGIN_SRC, 'plugins', 'claude-code-kanban', 'scripts', 'context-status.sh');
-const CTX_SCRIPT_DEST = path.join(HOOKS_DIR, 'context-status.sh');
+const CTX_SCRIPT_NAME = 'context-status.sh';
+const CTX_SCRIPT_SRC = path.join(PLUGIN_SRC, 'plugins', 'claude-code-kanban', 'scripts', CTX_SCRIPT_NAME);
+const CTX_SCRIPT_DEST = path.join(HOOKS_DIR, CTX_SCRIPT_NAME);
+const CTX_COMMAND = displayPath(CTX_SCRIPT_DEST);
 
 // ANSI helpers
 const green = s => `\x1b[32m${s}\x1b[0m`;
@@ -34,7 +38,7 @@ function prompt(question) {
 
 function runCLI(cmd, okPatterns = []) {
   try {
-    const out = execSync(cmd, { encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] }).trim();
+    const out = execSync(cmd, { encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'], env: CLI_ENV }).trim();
     return { ok: true, output: out };
   } catch (e) {
     const stderr = e.stderr?.trim() || e.message;
@@ -78,6 +82,7 @@ function copyDirSync(src, dest) {
 
 async function runInstall({ pluginOnly = false } = {}) {
   console.log(`\n  ${bold('claude-code-kanban')} — ${pluginOnly ? 'Plugin installer' : 'Plugin & StatusLine installer'}\n`);
+  console.log(`  Claude config dir: ${dim(displayPath(CLAUDE_DIR))}\n`);
   let failed = false;
 
   // 1. Check prerequisites
@@ -102,7 +107,7 @@ async function runInstall({ pluginOnly = false } = {}) {
   // 2. Copy plugin to stable location & register marketplace
   console.log(`\n  Plugin: ${dim(PLUGIN_DEST)}`);
   if (pluginOnly || await prompt(`    Install claude-code-kanban plugin? [Y/n] `)) {
-    process.stdout.write('    Copying plugin to ~/.claude/.cck/plugin... ');
+    process.stdout.write(`    Copying plugin to ${displayPath(PLUGIN_DEST)}... `);
     try {
       clearFilesRecursive(PLUGIN_DEST);
       copyDirSync(PLUGIN_SRC, PLUGIN_DEST);
@@ -178,8 +183,7 @@ async function runInstall({ pluginOnly = false } = {}) {
       return;
     }
 
-    const CTX_COMMAND = '~/.claude/hooks/context-status.sh';
-    const hasCtx = settings.statusLine?.command?.includes('context-status.sh');
+    const hasCtx = settings.statusLine?.command?.includes(CTX_SCRIPT_NAME);
     if (hasCtx) {
       console.log(`\n  StatusLine: ${green('✓')} Already configured`);
     } else if (!settings.statusLine) {
@@ -218,6 +222,7 @@ function printSummary(failed = false) {
 
 async function runUninstall() {
   console.log(`\n  ${bold('claude-code-kanban')} — Uninstaller\n`);
+  console.log(`  Claude config dir: ${dim(displayPath(CLAUDE_DIR))}\n`);
 
   // 1. Uninstall plugin via Claude CLI
   process.stdout.write('  Removing plugin... ');
@@ -260,9 +265,9 @@ async function runUninstall() {
       let changed = false;
 
       // Strip context-status.sh from statusLine
-      if (settings.statusLine?.command?.includes('context-status.sh')) {
+      if (settings.statusLine?.command?.includes(CTX_SCRIPT_NAME)) {
         const cmd = settings.statusLine.command;
-        const stripped = cmd.replace(/~\/\.claude\/hooks\/context-status\.sh\s*\|\s*/, '').trim();
+        const stripped = cmd.replace(new RegExp(`\\S*${CTX_SCRIPT_NAME.replace('.', '\\.')}\\s*\\|\\s*`), '').trim();
         if (stripped && stripped !== cmd) {
           settings.statusLine.command = stripped;
           console.log(`  StatusLine: ${green('✓')} Restored to "${stripped}"`);

package/lib/claude-dir.js

@@ -0,0 +1,53 @@
+const crypto = require('node:crypto');
+const os = require('node:os');
+const path = require('node:path');
+
+const DEFAULT_CLAUDE_DIR = path.join(os.homedir(), '.claude');
+
+// --name <value> | --name=<value>; null when absent.
+function getArgValue(name) {
+  const argv = process.argv;
+  const idx = argv.findIndex((arg) => arg === `--${name}` || arg.startsWith(`--${name}=`));
+  if (idx === -1) return null;
+  const arg = argv[idx];
+  if (arg.includes('=')) return arg.split('=').slice(1).join('=');
+  return argv[idx + 1] || null;
+}
+
+function expandHome(dir) {
+  return dir.replace(/^~/, os.homedir());
+}
+
+// --dir | CLAUDE_CONFIG_DIR | CLAUDE_DIR | ~/.claude
+function getClaudeDir() {
+  const dir = getArgValue('dir') || process.env.CLAUDE_CONFIG_DIR || process.env.CLAUDE_DIR;
+  return dir ? expandHome(dir) : DEFAULT_CLAUDE_DIR;
+}
+
+function isDefaultClaudeDir(dir) {
+  return path.resolve(dir) === path.resolve(DEFAULT_CLAUDE_DIR);
+}
+
+// localStorage is per browser origin, so every config dir served from the same port would
+// otherwise share last view, collapsed groups and sidebar layout. The default dir keeps the
+// bare keys; any other dir gets a prefix derived from its resolved path.
+function storageNamespace(dir) {
+  if (isDefaultClaudeDir(dir)) return null;
+  return `cfg-${crypto.createHash('sha1').update(path.resolve(dir)).digest('hex').slice(0, 8)}`;
+}
+
+// Env for spawning the claude CLI. Claude Code keeps .claude.json beside ~/.claude when
+// CLAUDE_CONFIG_DIR is unset but inside the dir when it is set, so the default dir must
+// stay unset rather than be spelled out.
+function claudeCliEnv(dir) {
+  return isDefaultClaudeDir(dir) ? process.env : { ...process.env, CLAUDE_CONFIG_DIR: dir };
+}
+
+// Home-relative, forward-slash form for messages and shell commands.
+function displayPath(p) {
+  const home = os.homedir();
+  const rel = p.startsWith(home) ? `~${p.slice(home.length)}` : p;
+  return rel.split(path.sep).join('/');
+}
+
+module.exports = { getArgValue, getClaudeDir, claudeCliEnv, displayPath, storageNamespace };

package/lib/open-editor.js

@@ -221,6 +221,7 @@ function execNoShell(cmd, args, opts = {}) {
     let argv = args;
     const spawnOpts = {
       cwd: opts.cwd || undefined,
+      env: opts.env,
       timeout: opts.timeout,
       windowsHide: true,
       stdio: ['ignore', 'pipe', 'pipe'],
@@ -258,7 +259,9 @@ function execNoShell(cmd, args, opts = {}) {
     child.on('error', reject);
     child.on('close', (code, signal) => {
       if (signal) return reject(new Error(`Command terminated by ${signal}: ${stderr.trim()}`));
-      if (code !== 0) return reject(new Error(stderr.trim() || `Command exited with code ${code}`));
+      // The claude CLI reports its own failures on stdout, so stderr alone is
+      // often empty and the caller would surface only the exit code.
+      if (code !== 0) return reject(new Error(stderr.trim() || stdout.trim() || `Command exited with code ${code}`));
       resolve({ stdout, stderr });
     });
   });

package/lib/parsers.js

@@ -303,14 +303,54 @@ function extractGoalFromLine(data) {
   if (data.type === 'attachment' && data.attachment?.type === 'goal_status') {
     return data.attachment.met ? null : { condition: data.attachment.condition || '' };
   }
-  if (data.type === 'user' && typeof data.message?.content === 'string'
-      && data.message.content.includes('<command-name>/goal</command-name>')
-      && /<command-args>\s*clear/.test(data.message.content)) {
+  // `/goal clear` is a type:system local_command line carrying the command
+  // markup in `content`; a user-typed command line carries it in message.content.
+  const content = data.content ?? data.message?.content;
+  if (typeof content === 'string' && content.includes(GOAL_COMMAND_TAG) && /<command-args>\s*clear/.test(content)) {
     return null;
   }
   return undefined;
 }
 
+const GOAL_COMMAND_TAG = '<command-name>/goal</command-name>';
+const GOAL_MARKERS = ['"goal_status"', GOAL_COMMAND_TAG].map((m) => Buffer.from(m));
+const SCAN_CHUNK = 65536;
+const scanBuf = Buffer.allocUnsafe(SCAN_CHUNK);
+
+// Streams [from, to) and calls onLine for the complete lines of every chunk
+// that contains a marker. Chunks without one are never decoded, which keeps a
+// full pass close to raw read speed (measured ~4x cheaper than decode+split).
+function scanMarkedLines(fd, from, to, markers, onLine) {
+  let carry = Buffer.alloc(0);
+  let offset = from;
+  while (offset < to) {
+    const n = fs.readSync(fd, scanBuf, 0, Math.min(SCAN_CHUNK, to - offset), offset);
+    if (n === 0) break;
+    offset += n;
+    const view = carry.length ? Buffer.concat([carry, scanBuf.subarray(0, n)]) : scanBuf.subarray(0, n);
+    const cut = view.lastIndexOf(0x0a) + 1;
+    const body = view.subarray(0, cut);
+    carry = Buffer.from(view.subarray(cut));
+    if (markers.some((m) => body.includes(m))) for (const line of body.toString('utf8').split('\n')) onLine(line);
+  }
+  if (carry.length && markers.some((m) => carry.includes(m))) onLine(carry.toString('utf8'));
+}
+
+// Goal events are rare and can sit anywhere in a long JSONL, outside both the
+// head and tail windows. Returns the last goal update in [from, to), or
+// undefined when there is none.
+function scanGoalInRange(fd, from, to) {
+  let latest;
+  scanMarkedLines(fd, from, to, GOAL_MARKERS, (line) => {
+    if (!line.includes('"goal_status"') && !line.includes(GOAL_COMMAND_TAG)) return;
+    try {
+      const update = extractGoalFromLine(JSON.parse(line));
+      if (update !== undefined) latest = update;
+    } catch (_) {}
+  });
+  return latest;
+}
+
 // gitBranch in the JSONL is pinned to the launch-time repo by Claude Code
 // and goes stale once cwd shifts (Bash `cd`, submodule). Callers needing the
 // live branch must resolve it from cwd separately. Cache is reset on inode
@@ -392,6 +432,12 @@ function readSessionInfoFromJsonl(jsonlPath) {
       if (deltaLen > 0) {
         const readLen = Math.min(deltaLen, DELTA_MAX);
         const readStart = stat.size - readLen;
+        // The bytes an over-cap delta skips may hold a goal set, met or clear;
+        // scanned first so the delta's own lines win by order.
+        if (deltaLen > DELTA_MAX) {
+          const skipped = scanGoalInRange(fd, cached.scannedUpTo, readStart);
+          if (skipped !== undefined) result.goal = skipped;
+        }
         const buf = Buffer.alloc(readLen);
         const n = fs.readSync(fd, buf, 0, readLen, readStart);
         if (n > 0) {
@@ -452,7 +498,11 @@ function readSessionInfoFromJsonl(jsonlPath) {
           } catch (e) {}
         }
         if (latestTailCwd) lastCwdSeen = latestTailCwd;
-        if (tailGoal !== undefined) result.goal = tailGoal;
+        // A goal can be set, met or cleared between the head and tail windows.
+        // The scan starts at the head's last partial line and runs to EOF, so a
+        // tail event is simply seen again in order.
+        const goal = tailGoal !== undefined ? tailGoal : scanGoalInRange(fd, offset - Buffer.byteLength(leftover), stat.size);
+        if (goal !== undefined) result.goal = goal;
       }
       scannedUpTo = stat.size;
     }

package/package.json

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

package/plugin/plugins/claude-code-kanban/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-code-kanban",
-  "version": "2.10.0",
+  "version": "2.11.0",
   "description": "claude-code-kanban dashboard integration: agent activity tracking, context statusline, skills to drive the board from a session and to follow it",
   "experimental": {
     "monitors": "./monitors.json"

package/plugin/plugins/claude-code-kanban/scripts/agent-spy.sh

@@ -1,6 +1,6 @@
 #!/bin/bash
 # Tracks subagent lifecycle: one append-only JSONL file per agent, grouped by session
-# Layout: ~/.claude/.cck/agent-activity/{sessionId}/{agentId}.jsonl
+# Layout: <CLAUDE_CONFIG_DIR or ~/.claude>/.cck/agent-activity/{sessionId}/{agentId}.jsonl
 # Each line is a lifecycle event (start | idle | stop). Server folds last-line-wins.
 
 INPUT=$(cat)
@@ -17,7 +17,7 @@ eval "$(echo "$INPUT" | jq -r '
 
 [ -z "$SESSION_ID" ] && exit 0
 
-CCK_ACTIVITY="$HOME/.claude/.cck/agent-activity"
+CCK_ACTIVITY="${CLAUDE_CONFIG_DIR:-$HOME/.claude}/.cck/agent-activity"
 
 # Map session to custom task list on session start
 if [ "$EVENT" = "SessionStart" ]; then

package/plugin/plugins/claude-code-kanban/scripts/approval-gate.sh

@@ -4,11 +4,11 @@
 # is unchanged when the feature is off), then — only when explicitly enabled and
 # the board's server is alive — waits for a decision file written by the server.
 #
-# Contract (_plans/cck-ui-approvals/decisions.md):
-#   marker    ~/.claude/.cck/agent-activity/<sid>/_waiting.json            (D8: + id, cwd, permissionSuggestions)
-#   decision  ~/.claude/.cck/agent-activity/<sid>/_decision-<id>.json      (server writes it, Phase 3)
-#   config    ~/.claude/.cck/approvals.json {enabled, mode, waitSeconds}   (D2: fail-open when absent)
-#   liveness  ~/.claude/.cck/server.json {port, pid}                       (D1: a dead board costs nothing)
+# Contract (_plans/cck-ui-approvals/decisions.md), rooted at <CLAUDE_CONFIG_DIR or ~/.claude>/.cck:
+#   marker    agent-activity/<sid>/_waiting.json            (D8: + id, cwd, permissionSuggestions)
+#   decision  agent-activity/<sid>/_decision-<id>.json      (server writes it, Phase 3)
+#   config    approvals.json {enabled, mode, waitSeconds}   (D2: fail-open when absent)
+#   liveness  server.json {port, pid}                       (D1: a dead board costs nothing)
 #
 # First writer wins (D5): a terminal answer deletes the marker via PostToolUse
 # and this gate exits silently; a decision arriving after the tool already ran
@@ -37,7 +37,7 @@ KIND="permission"
 [ "$TOOL_NAME" = "AskUserQuestion" ] && KIND="question"
 [ "$TOOL_NAME" = "ExitPlanMode" ] && KIND="plan"
 
-CCK_DIR="$HOME/.claude/.cck"
+CCK_DIR="${CLAUDE_CONFIG_DIR:-$HOME/.claude}/.cck"
 DIR="$CCK_DIR/agent-activity/$SESSION_ID"
 MARKER="$DIR/_waiting.json"
 mkdir -p "$DIR"

package/plugin/plugins/claude-code-kanban/scripts/context-status.sh

@@ -1,6 +1,6 @@
 #!/bin/bash
 # Statusline spy: writes raw context data for kanban dashboard, passes input through
-# Layout: ~/.claude/.cck/context-status/{sessionId}.json
+# Layout: <CLAUDE_CONFIG_DIR or ~/.claude>/.cck/context-status/{sessionId}.json
 #
 # Usage: pipe before your statusline command:
 #   "command": "~/.claude/hooks/context-status.sh | npx -y ccstatusline@latest"
@@ -9,7 +9,7 @@ INPUT=$(cat)
 
 SESSION_ID=$(echo "$INPUT" | jq -r '.session_id // ""')
 if [ -n "$SESSION_ID" ]; then
-  DIR="$HOME/.claude/.cck/context-status"
+  DIR="${CLAUDE_CONFIG_DIR:-$HOME/.claude}/.cck/context-status"
   mkdir -p "$DIR"
   echo "$INPUT" > "$DIR/$SESSION_ID.json"
 fi

package/plugin/plugins/claude-code-kanban/scripts/postman.js

@@ -19,7 +19,8 @@ const os = require('os');
 const path = require('path');
 
 const SESSION_ID = process.env.CLAUDE_CODE_SESSION_ID;
-const SERVER_INFO = path.join(os.homedir(), '.claude', '.cck', 'server.json');
+const CLAUDE_DIR = process.env.CLAUDE_CONFIG_DIR || path.join(os.homedir(), '.claude');
+const SERVER_INFO = path.join(CLAUDE_DIR, '.cck', 'server.json');
 // The server caps its own wait at 120s. Sitting at the ceiling halves every recurring
 // cost -- handshake, route walk, timer, empty response -- and costs no event latency,
 // because an enqueue wakes the poll immediately.