claude-code-kanban 4.24.0 → 4.26.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
@@ -49,7 +51,7 @@ Tasks, agents, and messages appear on the board automatically — Claude Code wr
 - **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
-- **UI approvals (opt-in)** — Allow/deny permission asks and answer questions from the board — [docs](docs/ui-approvals.md)
+- **UI approvals** — Allow/deny permission asks and answer questions from the board; on by default, opt out per config dir — [docs](docs/ui-approvals.md)
 - **Agent teams** — Color-coded team members, owner filtering, member count badges
 - **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
@@ -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);
@@ -125,12 +130,27 @@ async function runInstall({ pluginOnly = false } = {}) {
     if (!upd.ok) console.log(`    ${yellow('⚠')} Marketplace refresh failed: ${upd.error}`);
 
     const inst = runCLI('claude plugin install claude-code-kanban@claude-code-kanban', ['already installed', 'already exists']);
+    const alreadyInstalled = inst.idempotent || /already installed/i.test(inst.output || '');
     if (inst.ok) {
-      console.log(`    ${green('✓')} ${inst.idempotent ? 'Already installed' : 'Plugin installed'}`);
+      console.log(`    ${green('✓')} ${alreadyInstalled ? 'Already installed' : 'Plugin installed'}`);
     } else {
       console.log(`    ${red('✗')} Plugin install failed: ${inst.error}`);
       failed = true;
     }
+
+    // `install` is a no-op once the plugin is present — it exits 0 and only says so
+    // on stdout — so a re-copied plugin keeps running from the old cached version
+    // until `update` pulls the new one in. That is how a config dir ends up serving
+    // a plugin older than the board it talks to.
+    if (alreadyInstalled) {
+      const upgrade = runCLI('claude plugin update claude-code-kanban', ['already at the latest']);
+      if (upgrade.ok) {
+        const line = (upgrade.output || '').split('\n').find(l => l.includes('updated from'));
+        console.log(`    ${green('✓')} ${line ? line.replace(/^[^A-Za-z]*/, '') : 'Already at the latest version'}`);
+      } else {
+        console.log(`    ${yellow('⚠')} Plugin update failed: ${upgrade.error}`);
+      }
+    }
   } else {
     console.log(`    ${dim('Skipped')}`);
   }
@@ -178,8 +198,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 +237,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 +280,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/approvals.js

@@ -63,20 +63,51 @@ function isDecisionFile(name) {
 // (PERMISSION_TTL_MS hides the card at 30 min, so waiting longer than the UI
 // can show the ask is strictly worse — D11); keep them in sync with
 // approval-gate.sh.
-const WAIT_SECONDS_DEFAULT = 30;
+const WAIT_SECONDS_DEFAULT = 1800;
 const WAIT_SECONDS_MAX = 1800;
 // Small grace over the gate's own deadline so a race never 410s a live hook
 const LAPSE_GRACE_MS = 5000;
-
 function waitSecondsFrom(cfg) {
   const raw = cfg && cfg.waitSeconds;
   if (Number.isInteger(raw) && raw >= 0) return Math.min(raw, WAIT_SECONDS_MAX);
   return WAIT_SECONDS_DEFAULT;
 }
 
+// Normalizes the `approvals` section of <CCK_DIR>/config.json. The gate is on
+// by default: only an explicit `enabled: false` turns it off, and anything
+// unparseable falls back to defaults — the same parse approval-gate.sh does.
+function approvalsFrom(cfg) {
+  const a = cfg && typeof cfg.approvals === 'object' && cfg.approvals ? cfg.approvals : {};
+  return {
+    enabled: a.enabled !== false,
+    mode: a.mode === 'permission' ? 'permission' : 'permission+question',
+    waitSeconds: waitSecondsFrom(a),
+  };
+}
+
+// Whether the hook waits for a board decision on a marker of this kind
+function isKindGated(kind, approvals) {
+  if (!approvals.enabled) return false;
+  if (kind === 'question') return approvals.mode === 'permission+question';
+  return true;
+}
+
+// Why the board may not answer this marker, or null when it may. Shared by the
+// session list (which hides the buttons) and the respond route (which refuses),
+// so the two can never disagree.
+function boardRefusal(marker, approvals, now = Date.now()) {
+  if (!isKindGated(marker.kind, approvals)) {
+    return { status: 410, error: 'UI approvals are off for this ask — answer it in the terminal' };
+  }
+  if (isLapsed(marker.timestamp, approvals.waitSeconds * 1000, now)) {
+    return { status: 410, error: 'Ask lapsed — answer it in the terminal' };
+  }
+  return null;
+}
+
 function isLapsed(timestamp, waitMs, now = Date.now()) {
   if (!timestamp) return true;
   return now - new Date(timestamp).getTime() > waitMs + LAPSE_GRACE_MS;
 }
 
-module.exports = { sanitizeRequestId, buildDecision, decisionFileName, isDecisionFile, waitSecondsFrom, isLapsed };
+module.exports = { sanitizeRequestId, buildDecision, decisionFileName, isDecisionFile, waitSecondsFrom, approvalsFrom, isKindGated, boardRefusal, isLapsed };

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;
     }
@@ -1246,6 +1296,69 @@ function buildAgentProgressMap(jsonlPath) {
   return buildSessionDigest(jsonlPath).progressMap;
 }
 
+const ARTIFACT_URL_RE = /https:\/\/claude\.ai\/\S*artifact\/[A-Za-z0-9_-]+/;
+
+function toolResultText(content) {
+  if (typeof content === 'string') return content;
+  if (!Array.isArray(content)) return '';
+  return content.filter(b => b?.type === 'text' && b.text).map(b => b.text).join('\n');
+}
+
+// Two kinds of line record a published artifact: the `frame-link` entry the
+// viewer writes, which carries the title, and the result of an Artifact publish,
+// which is there even when the artifact was never opened in a frame. Keyed by URL,
+// so the republishes of one page collapse into a single entry. A result counts
+// only when its tool_use_id belongs to a publish call — an artifact URL quoted
+// back by a grep or a file read would otherwise register another session's page as
+// this session's own, and a `read` of someone else's artifact is not a publish.
+function readArtifactLinks(jsonlPath) {
+  const byUrl = new Map();
+  const publishedFileByToolUseId = new Map();
+  const upsert = (url, ts) => {
+    let a = byUrl.get(url);
+    if (!a) {
+      a = { url, title: null, path: null, firstSeen: ts || null };
+      byUrl.set(url, a);
+    }
+    if (ts && (!a.firstSeen || ts < a.firstSeen)) a.firstSeen = ts;
+    return a;
+  };
+  try {
+    const content = readFileSync(jsonlPath, 'utf8');
+    for (const line of content.split('\n')) {
+      if (!line.includes('"frame-link"') && !line.includes('"name":"Artifact"') && !line.includes('claude.ai'))
+        continue;
+      let obj;
+      try { obj = JSON.parse(line); } catch (_) { continue; }
+      if (obj.type === 'frame-link' && obj.frameUrl) {
+        const a = upsert(obj.frameUrl, obj.timestamp);
+        if (obj.title) a.title = obj.title;
+        if (obj.path) a.path = obj.path;
+        continue;
+      }
+      const blocks = obj?.message?.content;
+      if (!Array.isArray(blocks)) continue;
+      for (const b of blocks) {
+        if (b?.type === 'tool_use') {
+          const input = b.name === 'Artifact' ? b.input || {} : null;
+          // The publish action is the default one, so it is spelled by the file it
+          // takes rather than by a name.
+          if (b.id && input?.file_path && (!input.action || input.action === 'publish')) {
+            publishedFileByToolUseId.set(b.id, input.file_path);
+          }
+          continue;
+        }
+        if (b?.type !== 'tool_result' || !publishedFileByToolUseId.has(b.tool_use_id)) continue;
+        const m = toolResultText(b.content).match(ARTIFACT_URL_RE);
+        if (!m) continue;
+        const a = upsert(m[0], obj.timestamp);
+        if (!a.path) a.path = publishedFileByToolUseId.get(b.tool_use_id);
+      }
+    }
+  } catch (_) {}
+  return [...byUrl.values()].sort((x, y) => (x.firstSeen < y.firstSeen ? -1 : x.firstSeen > y.firstSeen ? 1 : 0));
+}
+
 function readCompactSummaries(jsonlPath) {
   const results = [];
   // Inline format: newer Claude Code stores the summary directly in the parent
@@ -1584,6 +1697,7 @@ module.exports = {
   buildAgentProgressMap,
   buildSessionDigest,
   readCompactSummaries,
+  readArtifactLinks,
   findTerminatedTeammates,
   extractPromptFromTranscript,
   extractModelFromTranscript,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-code-kanban",
-  "version": "4.24.0",
+  "version": "4.26.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.12.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

@@ -1,14 +1,14 @@
 #!/bin/bash
 # Blocking approval gate: lets the cck board answer a permission ask or an
 # AskUserQuestion. Always writes the _waiting.json marker first (badge behavior
-# 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.
+# is unchanged when the feature is off), then — unless config.json opts out, and
+# only while 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    config.json {approvals: {enabled, mode, waitSeconds}}  (on by default; absent = defaults)
+#   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"
@@ -61,37 +61,58 @@ echo "$INPUT" | jq -c --arg kind "$KIND" --arg ts "$TS" --arg id "$REQ_ID" '{
 # Every exit below leaves the marker in place for the badge; agent-spy.sh's
 # PostToolUse (or the server's TTL) retires it, exactly as before this feature.
 
-CONFIG="$CCK_DIR/approvals.json"
-[ -f "$CONFIG" ] || exit 0
-ENABLED=""
-eval "$(jq -r '
-  @sh "ENABLED=\(.enabled // false)",
-  @sh "MODE=\(.mode // "permission")",
-  @sh "WAIT_SECONDS=\(.waitSeconds // 30)"
-' < "$CONFIG" 2>/dev/null)"
-[ "$ENABLED" = "true" ] || exit 0
+# Defaults mirror lib/approvals.js — keep in sync. A missing or unparseable
+# config.json means defaults, i.e. the gate is on.
+ENABLED="true"
+MODE="permission+question"
+WAIT_SECONDS=""
+CONFIG="$CCK_DIR/config.json"
+if [ -f "$CONFIG" ]; then
+  eval "$(jq -r '
+    @sh "ENABLED=\(if .approvals.enabled == false then "false" else "true" end)",
+    @sh "MODE=\(.approvals.mode // "permission+question")",
+    @sh "WAIT_SECONDS=\(.approvals.waitSeconds // "")"
+  ' < "$CONFIG" 2>/dev/null)"
+fi
+[ "$ENABLED" = "false" ] && exit 0
 
 if [ "$KIND" = "question" ] && [ "$MODE" != "permission+question" ]; then
   exit 0
 fi
 
-case "$WAIT_SECONDS" in *[!0-9]* | "") WAIT_SECONDS=30 ;; esac
+case "$WAIT_SECONDS" in *[!0-9]* | "") WAIT_SECONDS=1800 ;; esac
 # PERMISSION_TTL_MS hides the card at 30 min — waiting longer than the UI can
 # show the ask is strictly worse than giving up (D11)
 [ "$WAIT_SECONDS" -gt 1800 ] && WAIT_SECONDS=1800
 
 SERVER_INFO="$CCK_DIR/server.json"
-[ -f "$SERVER_INFO" ] || exit 0
-SERVER_PORT=$(jq -r '.port // empty' < "$SERVER_INFO" 2>/dev/null)
-[ -n "$SERVER_PORT" ] || exit 0
+
 # A TCP connect beats a pid probe: it proves the board is actually serving, and
 # it works in the stripped environment Claude Code spawns hooks into, where
-# kill -0 cannot see native Windows pids and ps may be missing from PATH
-(: < "/dev/tcp/127.0.0.1/$SERVER_PORT") 2>/dev/null || exit 0
+# kill -0 cannot see native Windows pids and ps may be missing from PATH. The
+# port is re-read on every probe, not cached: under the hub every sub-app binds
+# an ephemeral port, so a board that restarts mid-wait comes back on a new one.
+# $(<file) and =~ keep the probe free of jq and cat spawns (~280 ms each here).
+board_alive() {
+  local raw port
+  raw=$(<"$SERVER_INFO") 2>/dev/null || return 1
+  [[ $raw =~ \"port\"[[:space:]]*:[[:space:]]*([0-9]+) ]] || return 1
+  port=${BASH_REMATCH[1]}
+  (: < "/dev/tcp/127.0.0.1/$port") 2>/dev/null
+}
 
 DECISION="$DIR/_decision-$REQ_ID.json"
 # EPOCHSECONDS (bash 5) keeps the poll loop free of `date` spawns
 DEADLINE=$((EPOCHSECONDS + WAIT_SECONDS))
+# Probing once up front made one unreachable moment disarm the whole ask, so a
+# board restarting on a new port (every hub-spawned sub-app binds an ephemeral
+# one) took the ask with it. Probe on a cadence instead and only give up once
+# the board has been gone for the whole grace. The terminal prompt stays live
+# throughout either way.
+BOARD_PROBE_SECONDS=5
+BOARD_GRACE_SECONDS=15
+NEXT_PROBE=0
+UNREACHABLE_SINCE=0
 
 while :; do
   if [ -f "$DECISION" ]; then
@@ -136,6 +157,20 @@ while :; do
   IFS= read -r CUR_MARKER < "$MARKER" 2>/dev/null || exit 0
   case "$CUR_MARKER" in *"\"id\":\"$REQ_ID\""*) ;; *) exit 0 ;; esac
 
+  if [ "$EPOCHSECONDS" -ge "$NEXT_PROBE" ]; then
+    NEXT_PROBE=$((EPOCHSECONDS + BOARD_PROBE_SECONDS))
+    # No beacon at all = no board on this config dir, now or a moment ago: give
+    # up at once, exactly as before. A beacon whose port is closed is the
+    # restart window instead, so that one gets the grace.
+    [ -f "$SERVER_INFO" ] || exit 0
+    if board_alive; then
+      UNREACHABLE_SINCE=0
+    else
+      [ "$UNREACHABLE_SINCE" -eq 0 ] && UNREACHABLE_SINCE=$EPOCHSECONDS
+      [ $((EPOCHSECONDS - UNREACHABLE_SINCE)) -ge "$BOARD_GRACE_SECONDS" ] && exit 0
+    fi
+  fi
+
   [ "$EPOCHSECONDS" -ge "$DEADLINE" ] && exit 0
   sleep 0.5
 done

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.