ai-lens 0.8.89 → 0.8.91

package/.commithash

@@ -1 +1 @@
-690dd28
+8894c21

package/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 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.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.
+
 ## 0.8.89 — 2026-06-11
 - improve: `ai-lens import claude-code` (and the import step inside `init`) now shows a live progress spinner — transcripts scanned, events collected, batches shipping — instead of sitting silent for minutes on a large history. Terminal-only; piped/CI output is unchanged.
 

package/cli/hooks.js

@@ -967,6 +967,119 @@ 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 };
+}
+
 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/import/claude-code.js

@@ -88,7 +88,7 @@ export function resolveCutoff({ days, since, from }, now = new Date()) {
   const lower = from || since;
   if (lower) return new Date(Date.parse(lower)).toISOString();
   if (days === 0) return new Date(0).toISOString();
-  const d = Number.isInteger(days) && days >= 0 ? days : 30;
+  const d = Number.isInteger(days) && days >= 0 ? days : 90;
   return new Date(now.getTime() - d * DAY_MS).toISOString();
 }
 
@@ -284,7 +284,7 @@ async function drainSpool({ timeoutMs = 120_000 } = {}) {
 
 export default async function importClaudeCode(flags) {
   const {
-    days = 30, since = null, from = null, to = null, dryRun = false, projects = null,
+    days = 90, since = null, from = null, to = null, dryRun = false, projects = null,
     noRedact = false, analysisMaxAgeDays: amAgeFlag = 30,
   } = flags;
   const analysisMaxAgeDays = Number.isInteger(amAgeFlag) && amAgeFlag >= 0 ? amAgeFlag : 30;

package/cli/import.js

@@ -17,7 +17,7 @@ const INT_KEYS = new Set(['days', 'analysisMaxAgeDays']);
  * REAL import instead of a preview.)
  */
 export function parseFlags(argv) {
-  const flags = { days: 30, since: null, from: null, to: null, dryRun: false, projects: null, noRedact: false, analysisMaxAgeDays: 30 };
+  const flags = { days: 90, since: null, from: null, to: null, dryRun: false, projects: null, noRedact: false, analysisMaxAgeDays: 30 };
   const errors = [];
   for (let i = 0; i < argv.length; i++) {
     const arg = argv[i];

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,
   installClientFiles, readLensConfig, saveLensConfig, getVersionInfo,
   getClaudeCodeHookDefsWithPath, getClaudeCodeHookDefsWithProjectDir, getCursorHookDefsWithPath, getCodexHookDefsWithPath,
   cleanupLegacyHooks, cleanupOppositeScope, cleanupEmptyMcpJson, addCursorMcp, removeCursorMcp,
@@ -988,6 +989,35 @@ 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 && !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();
@@ -1251,7 +1281,11 @@ async function maybeOfferImportHistory(flags) {
   heading('Importing local history');
   try {
     const { default: importClaudeCode } = await import('./import/claude-code.js');
-    await importClaudeCode({ days: 30 }); // server URL + git identity were just configured
+    // 90 days, not 30: Claude Code's local retention (~30d default) bounds the
+    // volume anyway, but machines with longer retention get their full recent
+    // history. LLM-analysis cost stays capped by the importer's
+    // analysisMaxAgeDays=30 — older sessions land in metrics/cost rollups only.
+    await importClaudeCode({ days: 90 }); // server URL + git identity were just configured
   } catch (err) {
     error(`  Import failed: ${err.message}`);
     info('  You can retry later: `npx -y ai-lens import claude-code`');

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 } 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,44 @@ 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 (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.89",
+  "version": "0.8.91",
   "type": "module",
   "description": "Centralized session analytics for AI coding tools",
   "bin": {