ronds_ai 0.1.23 → 0.1.25

package/README.md

@@ -190,7 +190,7 @@ ronds_ai analyze claude
 
 行为与 Langfuse Claude Observability Plugin 一致，只采集 transcript 中的 `text`、`tool_use` 和 `tool_result`，不上传 `thinking` block。状态和日志保存在 `~/.ronds_ai/analyze/`。
 
-Langfuse 连接信息已内置，Trace 的 `userId` 使用当前操作系统用户名。可选配置：
+Langfuse 连接信息已内置，Trace 的 `userId` 优先使用当前项目的 `git user.email`，读取不到时回退到当前操作系统用户名。可选配置：
 
 - `CC_LANGFUSE_DEBUG=true`：启用详细日志
 - `CC_LANGFUSE_MAX_CHARS=<正整数>`：单个文本字段的最大字符数，默认 `20000`

package/bin/ronds_ai.js

@@ -62,10 +62,10 @@ const SUPPORTED_SOURCES = new Set(['claude', 'cursor', 'codex', 'hermes']);
 
 function printUsage() {
   process.stderr.write([
-    'Usage:',
-    '  ronds_ai record <tool>',
-    '  ronds_ai analyze claude',
-    '  ronds_ai check record',
+    'Usage:',
+    '  ronds_ai record <tool>',
+    '  ronds_ai analyze claude',
+    '  ronds_ai check record',
     '  ronds_ai doctor <tool>',
     '  ronds_ai hooks deploy [--scope project|user] [--tool cursor|claude|codex]',
     '  ronds_ai hooks deploy hermes',
@@ -78,8 +78,8 @@ function printUsage() {
     '  hermes',
     '',
     'Examples:',
-    '  npx ronds_ai@latest record claude',
-    '  npx ronds_ai@latest analyze claude',
+    '  npx ronds_ai@latest record claude',
+    '  npx ronds_ai@latest analyze claude',
     '  npx ronds_ai@latest record cursor',
     '  npx ronds_ai@latest check record',
     '  npx ronds_ai@latest doctor claude',
@@ -282,7 +282,7 @@ async function run() {
 
   maybeStartHooksAutoSync({ command, args });
 
-  if (command === 'record') {
+  if (command === 'record') {
     const [source] = args;
     const normalizedSource = String(source || '').trim().toLowerCase();
 
@@ -291,21 +291,21 @@ async function run() {
     }
 
     await runCodeRecord(normalizedSource);
-    return;
-  }
-
-  if (command === 'analyze') {
-    const [source] = args;
-    if (String(source || '').trim().toLowerCase() !== 'claude') {
-      throw new Error(`Unsupported analyze tool: ${source || ''}`);
-    }
-
-    // 仅在 analyze 分支中加载 Node 20+ 的可选 Langfuse 依赖，避免影响旧版 record。
-    const { runClaudeAnalyze } = require('../lib/analyze_claude');
-    await runClaudeAnalyze();
-    return;
-  }
-
+    return;
+  }
+
+  if (command === 'analyze') {
+    const [source] = args;
+    if (String(source || '').trim().toLowerCase() !== 'claude') {
+      throw new Error(`Unsupported analyze tool: ${source || ''}`);
+    }
+
+    // 仅在 analyze 分支中加载 Node 20+ 的可选 Langfuse 依赖，避免影响旧版 record。
+    const { runClaudeAnalyze } = require('../lib/analyze_claude');
+    await runClaudeAnalyze();
+    return;
+  }
+
   if (command === 'doctor') {
     const [tool] = args;
     const normalizedTool = String(tool || '').trim().toLowerCase();
@@ -342,14 +342,28 @@ async function run() {
   throw new Error(`Unsupported command: ${command || ''}`);
 }
 
-run().catch((error) => {
-  if (error && error.code === 'ANALYZE_PREFLIGHT') {
-    process.stderr.write(`${error.message}\n`);
-    process.exitCode = 1;
-    return;
-  }
-
-  const [, , command, ...args] = process.argv;
+run().catch((error) => {
+  if (error && error.code === 'ANALYZE_PREFLIGHT') {
+    // 旁路 analyze 预检未通过时静默跳过（如 Node 版本不满足或依赖缺失），避免干扰主流程或弹出警告
+    try {
+      const fs = require('fs');
+      const os = require('os');
+      const path = require('path');
+      const analyzeDir = path.join(os.homedir(), '.ronds_ai', 'analyze');
+      fs.mkdirSync(analyzeDir, { recursive: true });
+      fs.appendFileSync(
+        path.join(analyzeDir, 'langfuse_hook.log'),
+        `${new Date().toISOString()} [INFO] analyze preflight skipped: ${error.message}\n`,
+        'utf8',
+      );
+    } catch {
+      // 忽略日志写入错误
+    }
+    process.exitCode = 0;
+    return;
+  }
+
+  const [, , command, ...args] = process.argv;
   let savedPath = '';
 
   try {

package/lib/analyze_claude.js

@@ -44,19 +44,99 @@ function assertAnalyzeNodeVersion(version = process.versions.node) {
   }
 }
 
+/**
+ * 尝试解析并 require 指定的模块，支持常规 require 和 ~/.ronds_ai/analyze/node_modules 路径。
+ */
+function resolveAnalyzeModule(moduleName) {
+  try {
+    return require(moduleName);
+  } catch (error) {
+    if (error && error.code !== 'MODULE_NOT_FOUND') {
+      throw error;
+    }
+  }
+
+  return resolveIsolatedAnalyzeModule(moduleName);
+}
+
+/**
+ * 只从 analyze 隔离目录解析模块，避免把 npx 临时目录中的依赖误判为已完成预装。
+ * @param {string} moduleName - Node.js 模块名
+ * @param {string} analyzeDir - analyze 隔离目录
+ * @returns {object|null}
+ */
+function resolveIsolatedAnalyzeModule(moduleName, analyzeDir = ANALYZE_DIR) {
+  const customPath = path.join(analyzeDir, 'node_modules', moduleName);
+  try {
+    return require(customPath);
+  } catch (error) {
+    if (error && error.code !== 'MODULE_NOT_FOUND') {
+      throw error;
+    }
+  }
+
+  return null;
+}
+
+/**
+ * 检查 analyze 必需的依赖是否已就绪。
+ */
+function areAnalyzeDependenciesInstalled() {
+  try {
+    const otelSdk = resolveAnalyzeModule('@opentelemetry/sdk-node');
+    const langfuseOtel = resolveAnalyzeModule('@langfuse/otel');
+    const langfuseTracing = resolveAnalyzeModule('@langfuse/tracing');
+    return Boolean(
+      otelSdk && otelSdk.NodeSDK
+      && langfuseOtel && langfuseOtel.LangfuseSpanProcessor
+      && langfuseTracing && typeof langfuseTracing.startObservation === 'function',
+    );
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * 检查 analyze 隔离目录中的必需依赖是否已就绪。
+ * deploy 只能使用此检查，运行时仍可使用普通依赖优先、隔离目录兜底的策略。
+ * @param {string} analyzeDir - analyze 隔离目录
+ * @returns {boolean}
+ */
+function areIsolatedAnalyzeDependenciesInstalled(analyzeDir = ANALYZE_DIR) {
+  try {
+    const otelSdk = resolveIsolatedAnalyzeModule('@opentelemetry/sdk-node', analyzeDir);
+    const langfuseOtel = resolveIsolatedAnalyzeModule('@langfuse/otel', analyzeDir);
+    const langfuseTracing = resolveIsolatedAnalyzeModule('@langfuse/tracing', analyzeDir);
+    return Boolean(
+      otelSdk && otelSdk.NodeSDK
+      && langfuseOtel && langfuseOtel.LangfuseSpanProcessor
+      && langfuseTracing && typeof langfuseTracing.startObservation === 'function',
+    );
+  } catch {
+    return false;
+  }
+}
+
 /**
  * 懒加载 analyze 专用的可选 Langfuse 依赖。
  */
 function loadLangfuseSdk() {
   try {
-    const { NodeSDK } = require('@opentelemetry/sdk-node');
-    const { LangfuseSpanProcessor } = require('@langfuse/otel');
-    const tracing = require('@langfuse/tracing');
+    const otelSdk = resolveAnalyzeModule('@opentelemetry/sdk-node');
+    const langfuseOtel = resolveAnalyzeModule('@langfuse/otel');
+    const langfuseTracing = resolveAnalyzeModule('@langfuse/tracing');
+    if (
+      !otelSdk || !otelSdk.NodeSDK
+      || !langfuseOtel || !langfuseOtel.LangfuseSpanProcessor
+      || !langfuseTracing || typeof langfuseTracing.startObservation !== 'function'
+    ) {
+      throw new Error('Dependencies missing');
+    }
     return {
-      NodeSDK,
-      LangfuseSpanProcessor,
-      startObservation: tracing.startObservation,
-      propagateAttributes: tracing.propagateAttributes,
+      NodeSDK: otelSdk.NodeSDK,
+      LangfuseSpanProcessor: langfuseOtel.LangfuseSpanProcessor,
+      startObservation: langfuseTracing.startObservation,
+      propagateAttributes: langfuseTracing.propagateAttributes,
     };
   } catch {
     throw new AnalyzePreflightError(
@@ -102,11 +182,20 @@ function extractHookContext(payload) {
     return null;
   }
   const hookEventName = payload.hook_event_name || payload.hookEventName || '';
-  return {
+  const context = {
     sessionId,
     transcriptPath: resolvedPath,
     flushDeferredAgentTurns: hookEventName === 'SessionEnd',
   };
+  const projectDir = [
+    payload.cwd,
+    payload.workspace && payload.workspace.current_dir,
+    payload.workspace && payload.workspace.project_dir,
+  ].find((value) => typeof value === 'string' && value.trim());
+  if (projectDir) {
+    context.projectDir = path.resolve(projectDir);
+  }
+  return context;
 }
 
 /**
@@ -426,10 +515,7 @@ async function processHookContext(context, config, sdkModules) {
 async function runClaudeAnalyze() {
   assertAnalyzeNodeVersion();
   const sdkModules = loadLangfuseSdk();
-  const config = getAnalyzeConfig();
-  writeAnalyzeDebug('analyze hook started', config);
   const raw = await readStdin();
-  writeAnalyzeDebug(`stdin received ${raw.length} chars`, config);
   if (!raw.trim()) {
     return;
   }
@@ -438,18 +524,23 @@ async function runClaudeAnalyze() {
   try {
     payload = JSON.parse(raw);
   } catch (error) {
+    const config = getAnalyzeConfig();
     writeAnalyzeLog('INFO', `invalid hook payload: ${error.message}`, config);
     return;
   }
-  writeAnalyzeDebug(
-    `payload top-level keys: ${Object.keys(payload).sort().join(', ')}`,
-    config,
-  );
   const context = extractHookContext(payload);
   if (!context) {
+    const config = getAnalyzeConfig();
     writeAnalyzeLog('INFO', 'hook payload has no usable session or transcript', config);
     return;
   }
+  const config = getAnalyzeConfig(context.projectDir);
+  writeAnalyzeDebug('analyze hook started', config);
+  writeAnalyzeDebug(`stdin received ${raw.length} chars`, config);
+  writeAnalyzeDebug(
+    `payload top-level keys: ${Object.keys(payload).sort().join(', ')}`,
+    config,
+  );
 
   try {
     await processHookContext(context, config, sdkModules);
@@ -462,10 +553,15 @@ async function runClaudeAnalyze() {
 module.exports = {
   ANALYZE_DIR,
   AnalyzePreflightError,
+  areAnalyzeDependenciesInstalled,
+  areIsolatedAnalyzeDependenciesInstalled,
   assertAnalyzeNodeVersion,
   extractHookContext,
   getSessionStateKey,
+  loadLangfuseSdk,
   processHookContext,
   redactLogMessage,
+  resolveAnalyzeModule,
+  resolveIsolatedAnalyzeModule,
   runClaudeAnalyze,
 };

package/lib/analyze_config.js

@@ -1,4 +1,5 @@
 const os = require('os');
+const { runGit } = require('./git');
 
 // Langfuse 连接信息按产品要求从当前 Claude 配置写入源码。
 const LANGFUSE_PUBLIC_KEY = 'pk-lf-default-001';
@@ -46,15 +47,32 @@ function resolveSystemUsername() {
   return process.env.USERNAME || process.env.USER || 'unknown';
 }
 
+/**
+ * 读取当前项目的 Git 邮箱，与 record 上报的 git.user.email 保持一致。
+ */
+function resolveGitUserEmail(projectDir) {
+  const workingDirectory = typeof projectDir === 'string' && projectDir.trim()
+    ? projectDir.trim()
+    : process.env.CLAUDE_PROJECT_DIR || process.cwd();
+  return runGit(workingDirectory, ['config', 'user.email'], false).toLowerCase();
+}
+
+/**
+ * 解析 Langfuse 用户标识，优先使用 Git 邮箱并保留系统用户名兜底。
+ */
+function resolveAnalyzeUserId(projectDir) {
+  return resolveGitUserEmail(projectDir) || resolveSystemUsername();
+}
+
 /**
  * 返回 analyze 命令使用的固定 Langfuse 配置。
  */
-function getAnalyzeConfig() {
+function getAnalyzeConfig(projectDir) {
   return {
     publicKey: LANGFUSE_PUBLIC_KEY,
     secretKey: LANGFUSE_SECRET_KEY,
     baseUrl: LANGFUSE_BASE_URL,
-    userId: resolveSystemUsername(),
+    userId: resolveAnalyzeUserId(projectDir),
     debug: readBooleanOption('CC_LANGFUSE_DEBUG', false),
     maxChars: readPositiveIntegerOption('CC_LANGFUSE_MAX_CHARS', 20000),
     skillTags: readBooleanOption('CC_LANGFUSE_SKILL_TAGS', true),
@@ -64,5 +82,7 @@ function getAnalyzeConfig() {
 
 module.exports = {
   getAnalyzeConfig,
+  resolveAnalyzeUserId,
+  resolveGitUserEmail,
   resolveSystemUsername,
 };

package/lib/hooks_auto_sync.js

@@ -20,11 +20,15 @@ const { spawn } = require('child_process');
 
 /** 当前 hooks schema 版本。当用户级 hooks deploy 输出发生变化时 +1。 */
 // v2: 用户级 Claude settings 新增 Stop/SessionEnd analyze hook。
-const HOOKS_SCHEMA_VERSION = 2;
+// v3: 优化 analyze 依赖预装到独立目录并守门。
+const HOOKS_SCHEMA_VERSION = 3;
 
 /** sentinel 有效时长：24 小时 */
 const HOOKS_AUTO_SYNC_CHECK_TTL_MS = 24 * 60 * 60 * 1000;
 
+/** analyze 依赖安装失败后的重试间隔：24 小时 */
+const ANALYZE_DEPENDENCY_RETRY_TTL_MS = 24 * 60 * 60 * 1000;
+
 /** lock 文件视为 stale 的超时时长：10 分钟 */
 const STALE_LOCK_TIMEOUT_MS = 10 * 60 * 1000;
 
@@ -119,12 +123,14 @@ function readHooksAutoSyncState() {
 
 /**
  * 写入 hooks_state.json。
- * @param {{ schemaVersion?: number, lastCheckedAt?: number, lastSyncedAt?: number }} state
+ * @param {{ schemaVersion?: number, analyzeReady?: boolean, lastAnalyzeAttemptAt?: number, lastCheckedAt?: number, lastSyncedAt?: number }} state
  */
 function writeHooksAutoSyncState(state) {
   ensureAutoSyncDir();
   const data = {
     schemaVersion: Number(state.schemaVersion) || 0,
+    analyzeReady: state.analyzeReady === true,
+    lastAnalyzeAttemptAt: Number(state.lastAnalyzeAttemptAt) || 0,
     lastCheckedAt: Number(state.lastCheckedAt) || 0,
     lastSyncedAt: Number(state.lastSyncedAt) || 0,
   };
@@ -156,9 +162,10 @@ function shouldSkipHooksAutoSync(command) {
  *
  * @param {object} state - 从状态文件读取的状态
  * @param {number} now - Date.now()
+ * @param {string} nodeVersion - 当前 Node.js 版本
  * @returns {'skip' | 'update-timestamp' | 'schedule'}
  */
-function shouldScheduleHooksAutoSync(state, now) {
+function shouldScheduleHooksAutoSync(state, now, nodeVersion = process.versions.node) {
   const lastCheckedAt = Number(state.lastCheckedAt || 0);
 
   // 仍在 TTL 窗口内，跳过
@@ -168,8 +175,15 @@ function shouldScheduleHooksAutoSync(state, now) {
 
   const schemaVersion = Number(state.schemaVersion || 0);
 
-  // 版本已是最新，仅更新时间戳
+  // schema 已更新但 analyze 依赖未就绪时，按独立间隔重试安装。
   if (schemaVersion >= HOOKS_SCHEMA_VERSION) {
+    const nodeMajor = Number(String(nodeVersion || '').replace(/^v/i, '').split('.')[0]);
+    if (nodeMajor >= 20 && state.analyzeReady !== true) {
+      const lastAnalyzeAttemptAt = Number(state.lastAnalyzeAttemptAt || 0);
+      if (now - lastAnalyzeAttemptAt >= ANALYZE_DEPENDENCY_RETRY_TTL_MS) {
+        return 'schedule';
+      }
+    }
     return 'update-timestamp';
   }
 
@@ -232,6 +246,8 @@ function maybeStartHooksAutoSync({ command, args } = {}) {
     if (decision === 'update-timestamp') {
       writeHooksAutoSyncState({
         schemaVersion: Number(state.schemaVersion || 0),
+        analyzeReady: state.analyzeReady === true,
+        lastAnalyzeAttemptAt: Number(state.lastAnalyzeAttemptAt || 0),
         lastCheckedAt: now,
         lastSyncedAt: Number(state.lastSyncedAt || 0),
       });
@@ -324,7 +340,7 @@ function releaseHooksAutoSyncLock(fd) {
  * 此函数由后台子进程（ronds_ai internal hooks auto-sync）调用。
  * 不向 stdout 输出，错误写入本地日志文件。
  */
-function runHooksAutoSync() {
+function runHooksAutoSync(options = {}) {
   const lock = acquireHooksAutoSyncLock();
   if (!lock) return; // 已有进程在同步
 
@@ -332,14 +348,23 @@ function runHooksAutoSync() {
 
   try {
     const { deployHooks, deployHermesHook } = require('./hooks_deploy');
+    const previousState = readHooksAutoSyncState();
 
-    deployHooks(os.homedir(), { scope: 'user' });
+    const deployResult = deployHooks(os.homedir(), { scope: 'user' });
     deployHermesHook();
 
+    const nodeVersion = options.nodeVersion || process.versions.node;
+    const nodeMajor = Number(String(nodeVersion || '').replace(/^v/i, '').split('.')[0]);
+    const analyzeRequired = nodeMajor >= 20;
+    const analyzeReady = Boolean(deployResult?.analyze?.installed);
+    const syncComplete = !analyzeRequired || analyzeReady;
+
     writeHooksAutoSyncState({
       schemaVersion: HOOKS_SCHEMA_VERSION,
+      analyzeReady,
+      lastAnalyzeAttemptAt: analyzeRequired ? now : Number(previousState.lastAnalyzeAttemptAt || 0),
       lastCheckedAt: now,
-      lastSyncedAt: now,
+      lastSyncedAt: syncComplete ? now : Number(previousState.lastSyncedAt || 0),
     });
     touchAutoSyncSentinel(now);
   } catch (error) {
@@ -382,6 +407,7 @@ function saveHooksAutoSyncError(error) {
 // ---------------------------------------------------------------------------
 
 module.exports = {
+  ANALYZE_DEPENDENCY_RETRY_TTL_MS,
   HOOKS_SCHEMA_VERSION,
   maybeStartHooksAutoSync,
   runHooksAutoSync,

package/lib/hooks_deploy.js

@@ -1,8 +1,13 @@
-const fs = require('fs');
+const { execFileSync } = require('child_process');
+const fs = require('fs');
 const os = require('os');
 const path = require('path');
 const commentJson = require('comment-json');
 const yaml = require('js-yaml');
+const {
+  ANALYZE_DIR,
+  areIsolatedAnalyzeDependenciesInstalled,
+} = require('./analyze_claude');
 
 const CURSOR_COMMAND = 'npx ronds_ai@latest record cursor';
 const CLAUDE_COMMAND = 'npx ronds_ai@latest record claude';
@@ -269,7 +274,7 @@ function splitClaudeAnalyzeEntries(entries) {
  * 在 Claude settings 中确保 Stop/SessionEnd 的 analyze hook 条目。
  * 只管理命令完全等于 CLAUDE_ANALYZE_COMMAND 的 hook，保留用户自定义条目。
  */
-function ensureClaudeAnalyzeHooks(config) {
+function ensureClaudeAnalyzeHooks(config) {
   const next = isPlainObject(config) ? { ...config } : {};
   const hooks = isPlainObject(next.hooks) ? { ...next.hooks } : {};
 
@@ -286,8 +291,59 @@ function ensureClaudeAnalyzeHooks(config) {
   }
 
   next.hooks = hooks;
-  return next;
-}
+  return next;
+}
+
+/**
+ * 从 Claude settings 的 Stop/SessionEnd 中移除本工具管理的 analyze hook。
+ * 仅删除命令完全相等的 command hook，并保留用户自定义 entry 与命令。
+ * @param {object} config - Claude settings 配置
+ * @returns {object}
+ */
+function removeClaudeAnalyzeHooks(config) {
+  const next = isPlainObject(config) ? { ...config } : {};
+  if (!isPlainObject(next.hooks)) {
+    return next;
+  }
+
+  const hooks = { ...next.hooks };
+  for (const eventName of CLAUDE_ANALYZE_EVENTS) {
+    const entries = Array.isArray(hooks[eventName]) ? hooks[eventName] : [];
+    const cleanedEntries = [];
+
+    for (const entry of entries) {
+      if (!isPlainObject(entry) || !Array.isArray(entry.hooks)) {
+        cleanedEntries.push(entry);
+        continue;
+      }
+
+      const filteredHooks = entry.hooks.filter(
+        (hook) => !(isPlainObject(hook)
+          && hook.type === 'command'
+          && hook.command === CLAUDE_ANALYZE_COMMAND),
+      );
+
+      if (filteredHooks.length === entry.hooks.length) {
+        cleanedEntries.push(entry);
+      } else if (filteredHooks.length > 0) {
+        cleanedEntries.push({ ...entry, hooks: filteredHooks });
+      }
+    }
+
+    if (cleanedEntries.length > 0) {
+      hooks[eventName] = cleanedEntries;
+    } else {
+      delete hooks[eventName];
+    }
+  }
+
+  if (Object.keys(hooks).length > 0) {
+    next.hooks = hooks;
+  } else {
+    delete next.hooks;
+  }
+  return next;
+}
 
 function ensureCodexHooksFeatureFlag(toml) {
   const newline = toml.includes('\r\n') ? '\r\n' : '\n';
@@ -584,14 +640,70 @@ function deployCursorHook(cursorPath, result) {
   recordWriteResult(cursorPath, cursorResult.exists, changed, result);
 }
 
+/**
+ * 确保 analyze 所需的依赖在 ~/.ronds_ai/analyze/ 中安装就绪。
+ * 成功或已存在返回 true；安装失败返回 false。
+ */
+function ensureAnalyzeDependencies(options = {}) {
+  const analyzeDir = options.analyzeDir || ANALYZE_DIR;
+  const areDependenciesInstalled = options.areDependenciesInstalled
+    || areIsolatedAnalyzeDependenciesInstalled;
+
+  if (areDependenciesInstalled(analyzeDir)) {
+    return true;
+  }
+
+  try {
+    ensureDir(analyzeDir);
+    if (typeof options.installDependencies === 'function') {
+      options.installDependencies(analyzeDir);
+      return areDependenciesInstalled(analyzeDir);
+    }
+
+    const npmCommand = process.platform === 'win32' ? 'npm.cmd' : 'npm';
+    const packages = [
+      '@langfuse/otel@^5.9.1',
+      '@langfuse/tracing@^5.9.1',
+      '@opentelemetry/sdk-node@^0.221.0',
+    ];
+    execFileSync(
+      npmCommand,
+      [
+        'install',
+        '--no-audit',
+        '--no-fund',
+        '--prefix',
+        analyzeDir,
+        ...packages,
+      ],
+      {
+        stdio: 'ignore',
+        timeout: 60000,
+        windowsHide: true,
+      },
+    );
+    return areDependenciesInstalled(analyzeDir);
+  } catch {
+    return false;
+  }
+}
+
 /**
  * 判断本次部署是否写入 Claude analyze hook。
  * 不满足条件时把原因写入 result.analyze.reason 并返回 false。
  */
-function shouldDeployClaudeAnalyze(result) {
-  const nodeMajor = getNodeMajorVersion();
-  if (nodeMajor < 20) {
-    result.analyze.reason = `analyze requires Node.js 20 or newer; current is ${process.versions.node || 'unknown'}`;
+function shouldDeployClaudeAnalyze(result, options = {}) {
+  const nodeVersion = options.nodeVersion || process.versions.node;
+  const nodeMajor = getNodeMajorVersion(nodeVersion);
+  if (nodeMajor < 20) {
+    result.analyze.reason = `analyze requires Node.js 20 or newer; current is ${nodeVersion || 'unknown'}`;
+    return false;
+  }
+
+  const ensureDependencies = options.ensureAnalyzeDependencies || ensureAnalyzeDependencies;
+  const dependenciesReady = ensureDependencies(options.dependencyOptions);
+  if (!dependenciesReady) {
+    result.analyze.reason = 'analyze dependencies failed to install or are unavailable';
     return false;
   }
 
@@ -602,8 +714,10 @@ function deployClaudeSettings(claudeSettingsPath, result, analyzeDeployed) {
   const claudeSettingsResult = readJsonFile(claudeSettingsPath, {});
   let nextClaudeSettings = ensureClaudeSettings(claudeSettingsResult.data);
 
-  if (analyzeDeployed) {
-    nextClaudeSettings = ensureClaudeAnalyzeHooks(nextClaudeSettings);
+  if (analyzeDeployed) {
+    nextClaudeSettings = ensureClaudeAnalyzeHooks(nextClaudeSettings);
+  } else {
+    nextClaudeSettings = removeClaudeAnalyzeHooks(nextClaudeSettings);
   }
 
   const changed = writeJsonFile(claudeSettingsPath, nextClaudeSettings);
@@ -683,7 +797,7 @@ function deployHooks(targetDir = process.cwd(), options = {}) {
   }
 
   if (!options.tool || options.tool === 'claude') {
-    const analyzeDeployed = shouldDeployClaudeAnalyze(result);
+    const analyzeDeployed = shouldDeployClaudeAnalyze(result, options.analyzeRuntime);
     deployClaudeSettings(paths.claudeSettingsPath, result, analyzeDeployed);
     if (analyzeDeployed) {
       result.analyze.installed = true;
@@ -787,6 +901,9 @@ function deployHermesHook() {
 module.exports = {
   deployHooks,
   deployHermesHook,
-  ensureClaudeAnalyzeHooks,
-  getNodeMajorVersion,
+  ensureAnalyzeDependencies,
+  ensureClaudeAnalyzeHooks,
+  getNodeMajorVersion,
+  removeClaudeAnalyzeHooks,
+  shouldDeployClaudeAnalyze,
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ronds_ai",
-  "version": "0.1.23",
+  "version": "0.1.25",
   "description": "CLI for reporting AI code edit events.",
   "bin": {
     "ronds_ai": "bin/ronds_ai.js"