ai-lens 0.8.90 → 0.8.92

package/.commithash

@@ -1 +1 @@
-9596d22
+2196993

package/CHANGELOG.md

@@ -2,6 +2,15 @@
 
 History of changes to the `ai-lens` CLI package on npm. New entries go on top. Format: `## X.Y.Z — YYYY-MM-DD`, followed by user-facing bullets.
 
+## 0.8.92 — 2026-06-11
+- fix: when global `~/.claude` hooks are active, `ai-lens init` no longer also installs the `.claude/settings.local.json` platform overlay (and removes a previously-written one) — global hooks already capture every project, and registering both made every hook event fire capture twice
+- improve: `ai-lens status` shows committed other-OS project hooks as healthy ("capture covered by global hooks") when global hooks are doing the work, instead of a false warning
+
+## 0.8.91 — 2026-06-11
+- fix: Claude Code hooks committed to a repo now work on both Windows and macOS/Linux. A committed `.claude/settings.json` can only carry one OS's `CLAUDE_PROJECT_DIR` syntax, so on the other OS hooks silently captured nothing; `ai-lens init` now writes the running OS's form into `.claude/settings.local.json` (per-machine, auto-gitignored) without touching the shared file
+- improve: `ai-lens status` correctly diagnoses committed project hooks — green when the platform overlay is in place, a clear fix hint when it's missing, and no more false "command path missing" on healthy setups
+- improve: `ai-lens remove` also cleans AI Lens hooks out of `.claude/settings.local.json`
+
 ## 0.8.90 — 2026-06-11
 - improve: the default import window for `ai-lens import claude-code` (and the import offer inside `init`) is now 90 days instead of 30 — machines with a longer Claude Code transcript retention get their full recent history. Auto-analysis still covers only the last 30 days; older sessions enter metrics and cost rollups.
 

package/cli/hooks.js

@@ -967,6 +967,156 @@ function isGitTracked(filePath) {
   }
 }
 
+// ---------------------------------------------------------------------------
+// Claude Code settings.local.json platform overlay
+// ---------------------------------------------------------------------------
+// A COMMITTED .claude/settings.json can carry only ONE CLAUDE_PROJECT_DIR syntax —
+// $VAR (POSIX sh) or %VAR% (Windows cmd.exe). Claude Code hands hook commands to the
+// native OS shell, so on the other OS the variable never expands and the hook
+// silently captures nothing. Upstream declined to fix or even document this
+// (anthropic/claude-code#24710, closed as not planned). Our fix: leave the committed
+// file alone (the anti-churn rule above) and mirror the hooks in the running OS's
+// form into .claude/settings.local.json — Claude Code's per-machine layer, which it
+// MERGES with settings.json at runtime and auto-gitignores. Both entries end up
+// registered: the wrong-form one dies silently, the overlay captures. If upstream
+// ever expands $VAR on Windows too, the double-fire collapses in the server's
+// content-hash dedup.
+
+/** Workspace-root-relative capture.js path out of a CLAUDE_PROJECT_DIR hook command. */
+export function extractProjectDirRelPath(cmd) {
+  if (!cmd) return null;
+  const n = String(cmd).replace(/\\/g, '/');
+  const m = n.match(/[$%]CLAUDE_PROJECT_DIR%?\/([^"']*ai-lens\/client\/capture\.js)/);
+  return m ? m[1] : null;
+}
+
+/** First AI Lens CLAUDE_PROJECT_DIR hook command in a Claude settings file, or null. */
+function findClaudeProjectDirCommand(configPath) {
+  try {
+    const config = JSON.parse(readFileSync(configPath, 'utf-8'));
+    if (!config.hooks || typeof config.hooks !== 'object') return null;
+    for (const entries of Object.values(config.hooks)) {
+      if (!Array.isArray(entries)) continue;
+      for (const entry of entries) {
+        if (!Array.isArray(entry?.hooks)) continue;
+        for (const h of entry.hooks) {
+          if (isClaudeProjectDirCommand(h?.command || '')) return h.command;
+        }
+      }
+    }
+  } catch { /* unreadable / malformed — no overlay decision possible */ }
+  return null;
+}
+
+export function claudeLocalSettingsPath(tool) {
+  return join(dirname(tool.configPath), 'settings.local.json');
+}
+
+/**
+ * Decide whether a Claude Code settings file needs the settings.local.json platform
+ * overlay on this machine.
+ *
+ * applicable ⇔ the file has AI Lens CLAUDE_PROJECT_DIR hooks in the OTHER OS's
+ * syntax AND is git-tracked (an untracked file is simply rewritten in place by the
+ * allowPlatformRewrite path instead — no overlay needed).
+ *
+ * @param {object} tool — Claude Code tool config ({ configPath, ... })
+ * @param {object} [opts] — { platform, tracked, ctx } overrides (tests)
+ */
+export function analyzeClaudeLocalOverlay(tool, opts = {}) {
+  const platform = opts.platform ?? process.platform;
+  const cmd = findClaudeProjectDirCommand(tool.configPath);
+  if (!cmd) return { applicable: false, reason: 'no CLAUDE_PROJECT_DIR ai-lens hooks' };
+  if (!isWrongPlatformProjectDirCommand(cmd, platform)) {
+    return { applicable: false, reason: 'platform syntax already correct' };
+  }
+  const tracked = opts.tracked ?? isGitTracked(tool.configPath);
+  if (!tracked) {
+    return { applicable: false, reason: 'untracked — init rewrites it in place' };
+  }
+  const rel = extractProjectDirRelPath(cmd);
+  if (!rel) return { applicable: false, reason: 'could not extract capture.js path from hook command' };
+
+  const localPath = claudeLocalSettingsPath(tool);
+  const localTool = {
+    ...tool,
+    name: `${tool.name} (settings.local.json overlay)`,
+    configPath: localPath,
+    // Never backup/rename a user's settings.local.json wholesale on parse errors.
+    sharedConfig: true,
+    hookDefs: getClaudeCodeHookDefsWithProjectDir(rel, { ...(opts.ctx ?? {}), platform }),
+  };
+  const overlayAnalysis = analyzeToolHooks(localTool, { platform, allowPlatformRewrite: true });
+  return {
+    applicable: true,
+    rel,
+    localPath,
+    localTool,
+    overlayCurrent: overlayAnalysis.status === 'current',
+    overlayStatus: overlayAnalysis.status,
+  };
+}
+
+/**
+ * Write (or refresh) the platform overlay decided by analyzeClaudeLocalOverlay.
+ * Merges into the existing settings.local.json, preserving everything that isn't an
+ * AI Lens hook. A malformed existing local file is left untouched (never destroy a
+ * user's local settings to install our hooks).
+ */
+export function writeClaudeLocalOverlay(tool, opts = {}) {
+  const a = opts.analysis ?? analyzeClaudeLocalOverlay(tool, opts);
+  if (!a.applicable) return { written: false, reason: a.reason };
+  if (a.overlayCurrent) return { written: false, reason: 'overlay already current', localPath: a.localPath };
+  let existing = null;
+  if (existsSync(a.localPath)) {
+    try {
+      existing = JSON.parse(readFileSync(a.localPath, 'utf-8'));
+    } catch {
+      return { written: false, reason: `${a.localPath} is malformed — fix or remove it first`, localPath: a.localPath };
+    }
+  }
+  const merged = buildMergedConfig(a.localTool, existing);
+  writeHooksConfig(a.localTool, merged);
+  return { written: true, localPath: a.localPath };
+}
+
+/**
+ * Whether GLOBAL Claude Code hooks (~/.claude/settings.json) are active on this
+ * machine — current AI Lens hooks and not disabled. When they are, the
+ * settings.local.json platform overlay is redundant: global hooks fire for every
+ * project, and registering both would double-capture each event (collapsed by the
+ * server's content-hash dedup, but pointless client work).
+ * @param {object} [globalTool] — override for tests (defaults to the real ~/.claude tool)
+ */
+export function globalClaudeHooksActive(globalTool = TOOL_CONFIGS.find(t => t.name === 'Claude Code')) {
+  if (!globalTool || !existsSync(globalTool.configPath)) return false;
+  if (analyzeToolHooks(globalTool).status !== 'current') return false;
+  return checkHooksDisabled(globalTool).length === 0;
+}
+
+/**
+ * Strip AI Lens hooks from the settings.local.json overlay (e.g. after global
+ * Claude Code hooks were installed and the overlay became a double-capture source).
+ * Preserves everything else in the file; refuses a malformed file.
+ */
+export function removeClaudeLocalOverlay(tool) {
+  const localPath = claudeLocalSettingsPath(tool);
+  if (!existsSync(localPath)) return { removed: false, reason: 'no settings.local.json' };
+  let config;
+  try {
+    config = JSON.parse(readFileSync(localPath, 'utf-8'));
+  } catch {
+    return { removed: false, reason: `${localPath} is malformed`, localPath };
+  }
+  const hasAiLens = config.hooks && typeof config.hooks === 'object'
+    && Object.values(config.hooks).some(en => Array.isArray(en) && en.some(e => isAiLensHook(e)));
+  if (!hasAiLens) return { removed: false, reason: 'no AI Lens hooks in overlay', localPath };
+  const probe = { ...tool, configPath: localPath, sharedConfig: true };
+  const stripped = buildStrippedConfig(probe, config);
+  writeHooksConfig(probe, stripped ?? {});
+  return { removed: true, localPath };
+}
+
 function isCurrentAiLensHook(entry, expected, opts = {}) {
   // "Current" = a GUI-safe install (launcher OR absolute-node capture.js) OR a
   // committed Claude Code $CLAUDE_PROJECT_DIR project hook. We do NOT require an exact

package/cli/init.js

@@ -15,6 +15,7 @@ import { migrateIfNeeded } from '../client/sender.js';
 import {
   CAPTURE_PATH, REPO_CAPTURE_PATH, detectInstalledTools, getCursorToolConfig, getClaudeCodeToolConfig, getCodexToolConfig,
   analyzeToolHooks, buildMergedConfig, writeHooksConfig, describePlan, enableCodexHookTrust,
+  analyzeClaudeLocalOverlay, writeClaudeLocalOverlay, removeClaudeLocalOverlay, globalClaudeHooksActive,
   installClientFiles, readLensConfig, saveLensConfig, getVersionInfo,
   getClaudeCodeHookDefsWithPath, getClaudeCodeHookDefsWithProjectDir, getCursorHookDefsWithPath, getCodexHookDefsWithPath,
   cleanupLegacyHooks, cleanupOppositeScope, cleanupEmptyMcpJson, addCursorMcp, removeCursorMcp,
@@ -988,6 +989,44 @@ export default async function init() {
     }
   }
 
+  // Cross-platform gap for COMMITTED Claude Code project hooks: a git-tracked
+  // .claude/settings.json carries one CLAUDE_PROJECT_DIR syntax, and on the other OS
+  // the hook silently never fires (cmd.exe vs sh; upstream anthropic/claude-code#24710
+  // closed as not planned). When the committed form doesn't match this OS, mirror the
+  // hooks into .claude/settings.local.json — Claude Code's per-machine layer
+  // (auto-gitignored, merged with settings.json at runtime). Runs regardless of
+  // --project-hooks: the committed file arrives with the clone, not via init.
+  if (!flags.noHooks) {
+    try {
+      const overlayProjectRoot = resolve(process.cwd());
+      const overlayClaudeTool = getClaudeCodeToolConfig(overlayProjectRoot, 'Claude Code (project)', ctx);
+      if (overlayClaudeTool && existsSync(overlayClaudeTool.configPath)) {
+        const overlay = analyzeClaudeLocalOverlay(overlayClaudeTool);
+        if (overlay.applicable && globalClaudeHooksActive()) {
+          // Global ~/.claude hooks fire for every project — an overlay would only
+          // double-register capture. Make sure it's absent rather than present.
+          const rm = removeClaudeLocalOverlay(overlayClaudeTool);
+          if (rm.removed) {
+            success(`  Claude Code: global hooks cover this project — removed the redundant overlay from ${rm.localPath}`);
+          } else {
+            info('  Claude Code: global hooks cover this project — settings.local.json overlay not needed.');
+          }
+        } else if (overlay.applicable && !overlay.overlayCurrent) {
+          const r = writeClaudeLocalOverlay(overlayClaudeTool, { analysis: overlay });
+          if (r.written) {
+            success(`  Claude Code: committed project hooks use the other OS's CLAUDE_PROJECT_DIR syntax — wrote this OS's form to ${r.localPath} (per-machine, not committed)`);
+          } else {
+            warn(`  Claude Code: platform overlay not written — ${r.reason}`);
+          }
+        } else if (overlay.applicable && overlay.overlayCurrent) {
+          info('  Claude Code: settings.local.json platform overlay already in place.');
+        }
+      }
+    } catch (err) {
+      warn(`  Claude Code platform overlay check failed: ${err.message}`);
+    }
+  }
+
   // Migrate legacy queue.jsonl → spool format (after user confirmation)
   try {
     const { migrated, errors: migErrors } = migrateIfNeeded();

package/cli/remove.js

@@ -9,7 +9,7 @@ import {
 } from './logger.js';
 import {
   detectInstalledTools, getCursorToolConfig, getClaudeCodeToolConfig, getCodexToolConfig, analyzeToolHooks,
-  buildStrippedConfig, writeHooksConfig, removeClientFiles, getVersionInfo,
+  buildStrippedConfig, writeHooksConfig, removeClientFiles, getVersionInfo, claudeLocalSettingsPath,
   cleanupLegacyHooks, cleanupEmptyMcpJson, removeCursorMcp, removeCodexHookTrust,
 } from './hooks.js';
 
@@ -45,6 +45,16 @@ export default async function remove() {
     tools = tools.filter(t => t.name !== 'Claude Code' || t.configPath !== projectClaude.configPath);
     tools.push(projectClaude);
   }
+  // The settings.local.json platform overlay (written by init for committed
+  // cross-platform hooks) holds AI Lens hooks of its own — strip it like any
+  // other config so remove leaves no live capture behind. sharedConfig: never
+  // delete or backup-rename the user's whole local settings file.
+  if (projectClaude) {
+    const localOverlayPath = claudeLocalSettingsPath(projectClaude);
+    if (existsSync(localOverlayPath)) {
+      tools.push({ ...projectClaude, name: 'Claude Code (project local overlay)', configPath: localOverlayPath, sharedConfig: true });
+    }
+  }
   const projectCodex = getCodexToolConfig(projectRoot, 'Codex (project)');
   if (projectCodex && existsSync(projectCodex.configPath)) {
     tools = tools.filter(t => t.name !== 'Codex' || t.configPath !== projectCodex.configPath);

package/cli/status.js

@@ -1,13 +1,13 @@
 import { existsSync, readFileSync, statSync, writeFileSync, readdirSync } from 'node:fs';
 import { execSync, spawnSync } from 'node:child_process';
-import { join } from 'node:path';
+import { join, dirname } from 'node:path';
 import { homedir, release as osRelease, arch as osArch } from 'node:os';
 import { randomUUID } from 'node:crypto';
 import tls from 'node:tls';
 
 import { TLS_TRUST_CODES, tlsCodeOf, tlsVerdictSummary, issuerName } from '../client/tls-trust.js';
 
-import { getVersionInfo, readLensConfig, detectInstalledTools, getCursorToolConfig, getClaudeCodeToolConfig, getCodexToolConfig, analyzeToolHooks, checkHooksDisabled, verifyCodexHookTrust, CAPTURE_PATH, TOOL_CONFIGS } from './hooks.js';
+import { getVersionInfo, readLensConfig, detectInstalledTools, getCursorToolConfig, getClaudeCodeToolConfig, getCodexToolConfig, analyzeToolHooks, checkHooksDisabled, verifyCodexHookTrust, CAPTURE_PATH, TOOL_CONFIGS, isClaudeProjectDirCommand, analyzeClaudeLocalOverlay, extractProjectDirRelPath, globalClaudeHooksActive } from './hooks.js';
 import { DATA_DIR, PENDING_DIR, SENDING_DIR, SESSION_PATHS_DIR, LOG_PATH, CAPTURE_LOG_PATH, LAST_STATUS_REPORT_PATH, getGitIdentity, getMonitoredProjects } from '../client/config.js';
 import { isLockStale } from '../client/sender.js';
 import { initLogger, info, success, warn, error, heading, blank } from './logger.js';
@@ -544,6 +544,51 @@ function checkHooks(tool) {
     };
   }
 
+  // CLAUDE_PROJECT_DIR project hooks: the var only expands at Claude Code runtime, so
+  // literal-path validation below would false-flag them. Validate the two things that
+  // actually break: capture.js missing at the project-relative path, and the committed
+  // file carrying the OTHER OS's variable syntax (which never expands here \u2014
+  // anthropic/claude-code#24710). The latter is healthy when the settings.local.json
+  // platform overlay is in place (written by init), red with a fix hint when it isn't.
+  if (mapped.ok === true && tool.dirPath && dirname(tool.dirPath) !== homedir()) {
+    const cmd = extractHookCommand(tool);
+    if (cmd && isClaudeProjectDirCommand(cmd)) {
+      const overlay = analyzeClaudeLocalOverlay(tool);
+      if (overlay.applicable) {
+        if (globalClaudeHooksActive()) {
+          return {
+            ok: true,
+            summary: 'committed hooks are for the other OS \u2014 capture covered by global hooks',
+            detail: `${detail}\n\nCommitted settings.json uses the other OS's CLAUDE_PROJECT_DIR syntax (never fires here), but global ~/.claude hooks are active and capture every project \u2014 no overlay needed.`,
+          };
+        }
+        if (overlay.overlayCurrent) {
+          return {
+            ok: true,
+            summary: 'hooks current (settings.local.json platform overlay)',
+            detail: `${detail}\n\nCommitted settings.json uses the other OS's CLAUDE_PROJECT_DIR syntax (never fires here); this machine captures via the overlay in ${overlay.localPath}.`,
+          };
+        }
+        return {
+          ok: false,
+          summary: "committed hooks use the other OS's CLAUDE_PROJECT_DIR syntax \u2014 never fire here",
+          detail: `${detail}\n\nThe committed .claude/settings.json hooks use the other OS's variable syntax, which this OS's shell does not expand (anthropic/claude-code#24710).\nFix: npx -y ai-lens init  (writes this OS's form to .claude/settings.local.json \u2014 per-machine, not committed)`,
+        };
+      }
+      // Correct platform form: resolve the project-relative path for a real existence check.
+      const rel = extractProjectDirRelPath(cmd);
+      const projectRoot = dirname(tool.dirPath);
+      if (rel && !existsSync(join(projectRoot, rel))) {
+        return {
+          ok: false,
+          summary: 'hooks current BUT capture.js missing in project',
+          detail: `${detail}\n\nCommand path issues:\n  \u2717 capture.js not found at: ${join(projectRoot, rel)}`,
+        };
+      }
+      return { ok: true, summary: mapped.label, detail };
+    }
+  }
+
   // Path validation: when hooks are present, verify command paths exist
   if (mapped.ok === true) {
     const pathIssues = validateHookCommandPaths(tool);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-lens",
-  "version": "0.8.90",
+  "version": "0.8.92",
   "type": "module",
   "description": "Centralized session analytics for AI coding tools",
   "bin": {