claude-code-kanban 6.0.0 → 6.1.0

package/README.md

@@ -21,25 +21,35 @@ Watch the tour on YouTube: [light](https://youtu.be/QbvDBFyfC7s), [dark](https:/
 
 You need Node.js 20 or later and the `claude` CLI.
 
-### 1. Install the integration (one time)
+### 1. Install the command
 
 ```bash
-npx claude-code-kanban --install
+npm install -g claude-code-kanban
+```
+
+To update, run the same command again.
+
+To try it without an install, run `npx claude-code-kanban --open`. npx keeps a copy of each version in its cache and can run an old copy, so use the global install to keep the board and to update it.
+
+### 2. Install the integration (one time)
+
+```bash
+claude-code-kanban --install
 ```
 
 The installer adds a Claude Code plugin with hooks, skills and a mod for context use and cost (Claude Code 2.1.287 or later). It asks before it installs and keeps your other settings. Without the hooks, the board shows tasks only: no agent log, no live activity, no waiting prompts.
 
-To remove it, run `npx claude-code-kanban --uninstall`. For another Claude config dir, pass the same `--dir=<path>` (or set `CLAUDE_CONFIG_DIR`) to `--install`, `--uninstall` and the server. See [Getting started](https://nikiforovall.blog/claude-code-kanban/getting-started/) for each install step.
+To remove it, run `claude-code-kanban --uninstall`. For another Claude config dir, pass the same `--dir=<path>` (or set `CLAUDE_CONFIG_DIR`) to `--install`, `--uninstall` and the server. See [Getting started](https://nikiforovall.blog/claude-code-kanban/getting-started/) for each install step.
 
-### 2. Start the board
+### 3. Start the board
 
 ```bash
-npx claude-code-kanban --open
+claude-code-kanban --open
 ```
 
-The board runs at `http://localhost:3541`. To install the command globally, run `npm install -g claude-code-kanban`, then `claude-code-kanban --open`.
+The board runs at `http://localhost:3541`.
 
-### 3. Use Claude Code as usual
+### 4. Use Claude Code as usual
 
 Run `claude` in any project. You do not configure anything per project. Claude Code writes task files and transcripts to the config dir, and the board watches them and sends each change to the browser.
 
@@ -107,10 +117,10 @@ Run `claude-code-kanban --help` or see the [CLI reference](https://nikiforovall.
 ## Configuration
 
 ```bash
-PORT=8080 npx claude-code-kanban               # Custom port. If it is busy, the server uses a random free port.
-npx claude-code-kanban --dir=~/.claude-work    # Another Claude config dir (or CLAUDE_CONFIG_DIR)
-npx claude-code-kanban --enable-terminal       # Turn on the embedded terminal
-EDITOR="code -w" npx claude-code-kanban        # Command for Open in editor (default: code)
+PORT=8080 claude-code-kanban               # Custom port. If it is busy, the server uses a random free port.
+claude-code-kanban --dir=~/.claude-work    # Another Claude config dir (or CLAUDE_CONFIG_DIR)
+claude-code-kanban --enable-terminal       # Turn on the embedded terminal
+EDITOR="code -w" claude-code-kanban        # Command for Open in editor (default: code)
 ```
 
 - The server listens on `127.0.0.1` only and has no authentication. To reach it from another machine, use `--host` and `--allowed-hosts`, and do it only on a network you trust.

package/lib/live-sessions.js

@@ -0,0 +1,39 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+// Claude Code's live-session registry: one <pid>.json per interactive claude.
+function readLiveSessions(sessionsDir) {
+  const sessions = [];
+  let files;
+  try {
+    files = fs.readdirSync(sessionsDir).filter((f) => f.endsWith('.json'));
+  } catch {
+    return sessions;
+  }
+  for (const file of files) {
+    try {
+      const s = JSON.parse(fs.readFileSync(path.join(sessionsDir, file), 'utf8'));
+      if (s?.sessionId && s.kind === 'interactive') {
+        sessions.push({ sessionId: s.sessionId, pid: s.pid || null, cwd: s.cwd || null, startedAt: s.startedAt || 0, status: s.status || null, name: s.name || null });
+      }
+    } catch { /* skip invalid */ }
+  }
+  return sessions;
+}
+
+// EPERM means the process exists but belongs to someone else.
+function isPidAlive(pid) {
+  try { process.kill(pid, 0); return true; } catch (e) { return e.code === 'EPERM'; }
+}
+
+// A registry file outlives a crashed claude, so the pid is probed rather than trusted.
+function isSessionLive(sessions, sessionId, exceptPid = null) {
+  return sessions.some((s) => {
+    if (s.sessionId !== sessionId || !s.pid || s.pid === exceptPid) return false;
+    return isPidAlive(s.pid);
+  });
+}
+
+module.exports = { readLiveSessions, isPidAlive, isSessionLive };

package/lib/parsers.js

@@ -373,13 +373,20 @@ const modeOf = (data) => {
   return (data.type === 'user' || data.type === 'permission-mode') && data.permissionMode || null;
 };
 
+// The TTL of the last prompt-cache write, from the API's 5m/1h split of cache_creation.
+const cacheTtlOf = (data) => {
+  const cc = data.type === 'assistant' && !data.isSidechain && data.message?.usage?.cache_creation;
+  if (!cc) return null;
+  return cc.ephemeral_1h_input_tokens > 0 ? '1h' : cc.ephemeral_5m_input_tokens > 0 ? '5m' : null;
+};
+
 // 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
 // change or truncation (size < scannedUpTo).
 
 function readSessionInfoFromJsonl(jsonlPath) {
-  const result = { slug: null, projectPath: null, cwd: null, gitBranch: null, customTitle: null, logicalParentUuid: null, compactBoundaryUuid: null, permissionMode: null };
+  const result = { slug: null, projectPath: null, cwd: null, gitBranch: null, customTitle: null, logicalParentUuid: null, compactBoundaryUuid: null, permissionMode: null, cacheTtl: null };
   let stat;
   let fd;
   try {
@@ -400,6 +407,7 @@ function readSessionInfoFromJsonl(jsonlPath) {
       logicalParentUuid: cached.logicalParentUuid || null,
       compactBoundaryUuid: cached.compactBoundaryUuid || null,
       permissionMode: cached.permissionMode || null,
+      cacheTtl: cached.cacheTtl || null,
       customTitle: readCustomTitle(jsonlPath, stat)
     };
   }
@@ -412,6 +420,7 @@ function readSessionInfoFromJsonl(jsonlPath) {
     result.logicalParentUuid = cached.logicalParentUuid || null;
     result.compactBoundaryUuid = cached.compactBoundaryUuid || null;
     result.permissionMode = cached.permissionMode || null;
+    result.cacheTtl = cached.cacheTtl || null;
   }
 
   let lastCwdSeen = result.cwd;
@@ -426,6 +435,8 @@ function readSessionInfoFromJsonl(jsonlPath) {
       if (data.gitBranch) result.gitBranch = data.gitBranch;
       const mode = modeOf(data);
       if (mode) result.permissionMode = mode;
+      const ttl = cacheTtlOf(data);
+      if (ttl) result.cacheTtl = ttl;
       if (data.subtype === 'compact_boundary' && data.logicalParentUuid && !result.logicalParentUuid) {
         result.logicalParentUuid = data.logicalParentUuid;
         // The boundary record's own uuid: a fork copies it verbatim from the
@@ -498,19 +509,22 @@ function readSessionInfoFromJsonl(jsonlPath) {
         const lines = tailBuf.toString('utf8', 0, tn).split('\n');
         let latestTailCwd = null;
         let latestTailMode = null;
+        let latestTailTtl = null;
         for (let i = lines.length - 1; i >= 0; i--) {
           try {
             const data = JSON.parse(lines[i]);
+            if (!latestTailTtl) latestTailTtl = cacheTtlOf(data);
             if (!result.slug && data.slug) result.slug = data.slug;
             if (!result.projectPath && data.cwd) result.projectPath = data.cwd;
             if (!result.gitBranch && data.gitBranch) result.gitBranch = data.gitBranch;
             if (!latestTailCwd && data.cwd) latestTailCwd = data.cwd;
             if (!latestTailMode) latestTailMode = modeOf(data);
-            if (latestTailCwd && latestTailMode && result.slug && result.projectPath && result.gitBranch) break;
+            if (latestTailCwd && latestTailMode && latestTailTtl && result.slug && result.projectPath && result.gitBranch) break;
           } catch {}
         }
         if (latestTailCwd) lastCwdSeen = latestTailCwd;
         if (latestTailMode) result.permissionMode = latestTailMode;
+        if (latestTailTtl) result.cacheTtl = latestTailTtl;
       }
       scannedUpTo = stat.size;
     }
@@ -533,7 +547,8 @@ function readSessionInfoFromJsonl(jsonlPath) {
       cwd: result.cwd,
       logicalParentUuid: result.logicalParentUuid,
       compactBoundaryUuid: result.compactBoundaryUuid,
-      permissionMode: result.permissionMode
+      permissionMode: result.permissionMode,
+      cacheTtl: result.cacheTtl
     });
     if (sessionInfoCache.size > SESSION_INFO_CACHE_MAX) {
       const firstKey = sessionInfoCache.keys().next().value;

package/lib/session-cache.js

@@ -4,7 +4,7 @@ const { exportParentVerdicts, importParentVerdicts, parentVerdictsDirty } = requ
 const { exportTaskCounts, importTaskCounts, taskCountsDirty } = require('./task-counts');
 
 // Bump when an entry's shape or meaning changes: a file with another version is ignored.
-const VERSION = 3;
+const VERSION = 4;
 // A cache this large is not one cck wrote for a normal set of transcripts. Rebuild it cold.
 const MAX_BYTES = 8 * 1024 * 1024;
 

package/lib/terminal-client.js

@@ -0,0 +1,221 @@
+'use strict';
+
+// cck's side of the terminal host (lib/terminal-host.js). cck keeps the gates it can check
+// alone (enabled, exposure, Host and Origin, the token) and the ids the host last reported,
+// so the board's sync callers stay sync; everything else is a call over IPC.
+
+const crypto = require('node:crypto');
+const { fork } = require('node:child_process');
+const path = require('node:path');
+const { tokenMatches, localUnavailableReason, refuseUpgrade, clientConfigFor } = require('./terminal');
+
+const HOST = path.join(__dirname, 'terminal-host.js');
+const CALL_TIMEOUT_MS = 15000;
+const MAX_RESTARTS = 3;
+const RESTART_WINDOW_MS = 60000;
+const RESTART_DELAY_MS = 1000;
+
+function hostError(message) {
+  return Object.assign(new Error(message), { status: 503 });
+}
+
+/**
+ * @param {object} o
+ * @param {ReturnType<typeof import('./terminal').readTerminalConfig>} o.config
+ * @param {{EXPOSED: boolean, upgradeVerdict: (req: any) => string|null}} o.net
+ * @param {string} o.claudeDir
+ * @param {boolean} o.isDefaultDir
+ * @param {string} o.sessionsDir  claude's live-session registry
+ * @param {(id: string) => string|null|Promise<string|null>} o.resolveCwd
+ * @param {(dir: string) => boolean|Promise<boolean>} o.isAllowedFolder
+ * @param {string} [o.token]
+ * @param {() => {sessions?: string[]}|null} [o.load]
+ * @param {(data: {sessions: string[]}) => void} [o.save]
+ * @param {() => void} [o.onChange]
+ * @param {(id: string) => void} [o.onExit]
+ */
+function createTerminalClient(o) {
+  const { config, net } = o;
+  const token = o.token || crypto.randomBytes(32).toString('hex');
+  const localReason = localUnavailableReason(config, net);
+  let child = null;
+  let hostReason = null;
+  let ids = [];
+  let serverUrl = null;
+  let restoreAsked = false;
+  let stopped = false;
+  let shuttingDown = false;
+  const restarts = [];
+  let nextCall = 0;
+  const calls = new Map();
+  let settle;
+  const started = new Promise((resolve) => { settle = resolve; });
+
+  function unavailableReason() {
+    if (localReason) return localReason;
+    if (stopped) return 'the terminal host stopped';
+    if (!child) return 'the terminal host is restarting';
+    return hostReason;
+  }
+
+  function spawn() {
+    hostReason = null;
+    const c = fork(HOST, [], { execArgv: [], windowsHide: true });
+    child = c;
+    c.on('message', (msg) => { if (c === child) onMessage(c, msg); });
+    c.on('exit', (code, signal) => { if (c === child) onHostExit(code, signal); });
+    c.on('error', () => {});
+    c.send({
+      t: 'init', config, claudeDir: o.claudeDir, isDefaultDir: o.isDefaultDir, sessionsDir: o.sessionsDir, token, serverUrl,
+      saved: config.restore ? o.load?.() ?? null : null,
+    });
+    if (restoreAsked) call('restore').catch(() => {});
+  }
+
+  function onMessage(c, msg) {
+    if (msg.t === 'state') {
+      hostReason = msg.reason;
+      ids = msg.ids;
+      settle(hostReason);
+      o.onChange?.();
+    } else if (msg.t === 'exit') o.onExit?.(msg.id);
+    else if (msg.t === 'save') o.save?.(msg.data);
+    else if (msg.t === 'reply') {
+      const pending = calls.get(msg.id);
+      if (!pending) return;
+      calls.delete(msg.id);
+      clearTimeout(pending.timer);
+      if (msg.error) pending.reject(new Error(msg.error));
+      else pending.resolve(msg.value);
+    } else if (msg.t === 'ask') answer(c, msg);
+  }
+
+  const ASKS = {
+    resolveCwd: [o.resolveCwd, null],
+    isAllowedFolder: [o.isAllowedFolder, false],
+  };
+
+  async function answer(c, msg) {
+    const [fn, fallback] = ASKS[msg.op];
+    let value;
+    try {
+      value = await fn(msg.arg);
+    } catch {
+      value = fallback;
+    }
+    if (c.connected) c.send({ t: 'answer', id: msg.id, value });
+  }
+
+  // The PTYs die with the host, as they do with cck; a new host resumes terminals.json.
+  function onHostExit(code, signal) {
+    child = null;
+    for (const pending of calls.values()) {
+      clearTimeout(pending.timer);
+      pending.reject(hostError('the terminal host stopped'));
+    }
+    calls.clear();
+    if (shuttingDown) return;
+    console.log(`Terminal host exited (${signal || code})`);
+    const lost = ids;
+    ids = [];
+    for (const id of lost) o.onExit?.(id);
+    o.onChange?.();
+    const now = Date.now();
+    while (restarts.length && now - restarts[0] > RESTART_WINDOW_MS) restarts.shift();
+    if (restarts.length >= MAX_RESTARTS) {
+      stopped = true;
+      console.log(`Terminal unavailable: the host stopped ${MAX_RESTARTS} times in ${RESTART_WINDOW_MS / 1000} s`);
+      settle(unavailableReason());
+      return;
+    }
+    restarts.push(now);
+    setTimeout(() => { if (!shuttingDown) spawn(); }, RESTART_DELAY_MS * restarts.length).unref();
+  }
+
+  function call(op, ...args) {
+    const c = child;
+    if (!c?.connected) return Promise.reject(hostError(unavailableReason() || 'the terminal host is not running'));
+    return new Promise((resolve, reject) => {
+      const id = ++nextCall;
+      const timer = setTimeout(() => {
+        calls.delete(id);
+        reject(hostError('the terminal host did not answer'));
+      }, CALL_TIMEOUT_MS);
+      calls.set(id, { resolve, reject, timer });
+      c.send({ t: 'call', id, op, args });
+    });
+  }
+
+  function handleUpgrade(req, socket, head) {
+    if (refuseUpgrade(req, socket, () => unavailableReason() || net.upgradeVerdict(req))) return;
+    // The client sends nothing before the 101, so no byte is lost between the two processes.
+    child.send({ t: 'upgrade', method: req.method, url: req.url, headers: req.headers, head: head.toString('base64') }, socket, (err) => {
+      if (err) socket.destroy();
+    });
+  }
+
+  function authorized(providedToken) {
+    return tokenMatches(token, providedToken);
+  }
+
+  function isRunning(id) {
+    return ids.includes(id);
+  }
+
+  async function startNew(msg, extraEnv) {
+    if (localReason) return { status: 403, error: localReason };
+    return call('startNew', msg, extraEnv);
+  }
+
+  async function end(id, providedToken) {
+    if (!authorized(providedToken)) return 'auth';
+    if (localReason) return 'not-found';
+    return call('end', id, providedToken);
+  }
+
+  async function paste(id, text) {
+    if (!isRunning(id)) return false;
+    return call('paste', id, text).catch(() => false);
+  }
+
+  function restore() {
+    restoreAsked = true;
+    if (child) call('restore').catch(() => {});
+  }
+
+  function setServerUrl(url) {
+    serverUrl = url;
+    if (child?.connected) child.send({ t: 'port', url });
+  }
+
+  // With no host there are no terminals, which the hub's eviction check must still read.
+  async function sessions() {
+    return child?.connected ? call('sessions') : [];
+  }
+
+  async function stats() {
+    const c = child;
+    return { hostPid: c?.pid ?? null, claudePids: c?.connected ? await call('claudePids') : {} };
+  }
+
+  function clientConfig() {
+    return clientConfigFor(config, !unavailableReason());
+  }
+
+  // Closing the channel is what ends the host, so it ends its PTYs itself.
+  function shutdown() {
+    shuttingDown = true;
+    try { child?.disconnect(); } catch { /* already closed */ }
+  }
+
+  if (localReason) settle(localReason);
+  else spawn();
+
+  return {
+    token, handleUpgrade, clientConfig, unavailableReason, authorized, isRunning, startNew, end, paste, restore,
+    setServerUrl, sessions, stats, shutdown, started,
+    ids: () => [...ids],
+  };
+}
+
+module.exports = { createTerminalClient };

package/lib/terminal-host.js

@@ -0,0 +1,95 @@
+'use strict';
+
+// The terminal's own process, forked by lib/terminal-client.js. It runs the terminal
+// service unchanged; cck reaches it only over the IPC channel and ends it by closing that.
+
+const { createTerminalService } = require('./terminal');
+const { readLiveSessions, isSessionLive } = require('./live-sessions');
+const { whichSync } = require('./open-editor');
+
+let service = null;
+let serverUrl = null;
+let lastState = null;
+let nextAsk = 0;
+const asks = new Map();
+
+function send(msg) {
+  if (process.connected) process.send(msg);
+}
+
+function ask(op, arg) {
+  return new Promise((resolve) => {
+    const id = ++nextAsk;
+    asks.set(id, resolve);
+    send({ t: 'ask', id, op, arg });
+  });
+}
+
+// The service reports every attach and detach too; cck needs only a change of ids or reason.
+function pushState() {
+  const state = { t: 'state', reason: service.unavailableReason(), ids: service.list().map((s) => s.id) };
+  const key = JSON.stringify(state);
+  if (key === lastState) return;
+  lastState = key;
+  send(state);
+}
+
+function init(msg) {
+  serverUrl = msg.serverUrl;
+  const liveSessions = () => readLiveSessions(msg.sessionsDir);
+  service = createTerminalService({
+    config: msg.config,
+    // cck checked Host, Origin and exposure before it handed the socket over.
+    net: { EXPOSED: false, upgradeVerdict: () => null },
+    claudeDir: msg.claudeDir,
+    isDefaultDir: msg.isDefaultDir,
+    token: msg.token,
+    serverUrl: () => serverUrl,
+    which: whichSync,
+    liveSessions,
+    isLiveElsewhere: (id, exceptPid) => isSessionLive(liveSessions(), id, exceptPid),
+    resolveCwd: (id) => ask('resolveCwd', id),
+    isAllowedFolder: (dir) => ask('isAllowedFolder', dir),
+    load: () => msg.saved,
+    save: (data) => send({ t: 'save', data }),
+    onChange: pushState,
+    onExit: (id) => send({ t: 'exit', id }),
+  });
+  pushState();
+}
+
+const CALLS = {
+  startNew: (msg, extraEnv) => service.startNew(msg, extraEnv),
+  end: (id, token) => service.end(id, token),
+  paste: (id, text) => service.paste(id, text),
+  restore: () => service.restore(),
+  sessions: () => service.list(),
+  claudePids: () => service.claudePids(),
+};
+
+async function call(msg) {
+  try {
+    send({ t: 'reply', id: msg.id, value: await CALLS[msg.op](...msg.args) });
+  } catch (e) {
+    send({ t: 'reply', id: msg.id, error: e.message });
+  }
+}
+
+process.on('message', (msg, socket) => {
+  if (msg.t === 'init') init(msg);
+  else if (msg.t === 'port') serverUrl = msg.url;
+  else if (msg.t === 'upgrade') {
+    if (!socket) return;
+    service.handleUpgrade({ method: msg.method, url: msg.url, headers: msg.headers }, socket, Buffer.from(msg.head, 'base64'));
+  } else if (msg.t === 'call') call(msg);
+  else if (msg.t === 'answer') {
+    asks.get(msg.id)?.(msg.value);
+    asks.delete(msg.id);
+  }
+});
+
+// cck is gone, so no claude may outlive the board that started it.
+process.on('disconnect', () => {
+  service?.shutdown();
+  process.exit(0);
+});