@ariso-ai/ari-hooks 0.1.5 → 0.1.7

package/README.md

@@ -33,12 +33,29 @@ That single command:
 
 Existing settings and hooks are preserved; running it again is a no-op.
 
+### Cursor
+
+Cursor's agent doesn't read `.claude/settings.json` — it has its own hooks
+system in `.cursor/hooks.json`. When `ari-hooks install` (or `init`) runs
+inside Cursor (detected via the `CURSOR_TRACE_ID` / `CURSOR_AGENT`
+environment variables Cursor sets in its terminal and CLI agent), it also
+writes the equivalent hooks there:
+
+- `sessionStart` — injects Ari's suggested tasks as agent context
+- `beforeSubmitPrompt` — records what you asked for
+- `afterAgentResponse` — captures the final assistant text (Cursor's
+  transcript isn't the Claude Code format, so the outcome is taken from
+  this event instead)
+- `stop` — sends the request/outcome pair to the Ari API
+
+`ari-hooks uninstall` cleans up both files, wherever it runs.
+
 ### Commands
 
 | Command | What it does |
 |---|---|
 | `ari-hooks install` | Login (if needed) + set up hooks in the current folder |
-| `ari-hooks uninstall` | Remove the hooks from `./.claude/settings.json` |
+| `ari-hooks uninstall` | Remove the hooks from `./.claude/settings.json` and `./.cursor/hooks.json` |
 | `ari-hooks login` | Browser login, stores the API token |
 | `ari-hooks init` | Just add the hooks to `./.claude/settings.json` (no login) |
 | `ari-hooks config` | Show configured URLs and login state |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ariso-ai/ari-hooks",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "description": "Set up Claude Code hooks that share your requests and their outcomes with Ari",
   "type": "module",
   "bin": {

package/src/cli.js

@@ -1,15 +1,21 @@
 import { login, logout, status } from './login.js';
-import { init, uninstall } from './init.js';
+import { init, install, uninstall } from './init.js';
 import { runHook } from './hooks.js';
 import { loadConfig, setUrls, showConfig } from './config.js';
 
 const USAGE = `ari-hooks — share your Claude Code activity with Ari
 
 Usage:
-  ari-hooks install      Log in (if needed) and set up hooks in the current folder
-  ari-hooks uninstall    Remove the hooks from ./.claude/settings.json
+  ari-hooks install      Log in (if needed) and set up hooks; asks whether to
+                         install for just this repo (and then just for you —
+                         .claude/settings.local.json — or everyone on the repo —
+                         .claude/settings.json) or machine-wide
+                         (inside Cursor, also writes ./.cursor/hooks.json)
+  ari-hooks uninstall    Remove the hooks from ./.claude/settings.json,
+                         ./.claude/settings.local.json, ~/.claude/settings.json,
+                         and ./.cursor/hooks.json
   ari-hooks login        Log in via the browser and store an API token
-  ari-hooks init         Just add the hooks to ./.claude/settings.json (no login)
+  ari-hooks init         Just add the hooks (no login)
   ari-hooks config       Show the configured URLs and login state
   ari-hooks status       Show login state
   ari-hooks logout       Remove the stored token
@@ -68,7 +74,7 @@ export async function main(argv) {
       if (!loadConfig().token) {
         await login();
       }
-      init();
+      await install();
       return;
     }
     case 'init':

package/src/hooks.js

@@ -58,15 +58,39 @@ function saveSession(sessionId, session) {
   writeFileSync(sessionPath(sessionId), JSON.stringify(session));
 }
 
+// Claude Code identifies the session as session_id; Cursor hooks send
+// conversation_id (their sessionStart also has a session_id, but the other
+// events do not, so the conversation is our stable per-turn key).
+const sessionIdOf = (input) => input.session_id ?? input.conversation_id;
+
+// Every Cursor hook payload carries cursor_version; Claude Code's never do.
+const isCursorInput = (input) => typeof input.cursor_version === 'string';
+
 /**
- * UserPromptSubmit: remember the prompt so the Stop hook can pair it with
- * the turn's outcome.
+ * UserPromptSubmit (Claude Code) / beforeSubmitPrompt (Cursor): remember the
+ * prompt so the Stop hook can pair it with the turn's outcome. Both hosts
+ * put the text in `prompt`.
  */
 async function onUserPromptSubmit(input) {
-  if (!input.session_id || typeof input.prompt !== 'string') return;
-  const session = loadSession(input.session_id);
+  const sessionId = sessionIdOf(input);
+  if (!sessionId || typeof input.prompt !== 'string') return;
+  const session = loadSession(sessionId);
   session.prompts.push(input.prompt);
-  saveSession(input.session_id, session);
+  saveSession(sessionId, session);
+}
+
+/**
+ * afterAgentResponse (Cursor only): Cursor's transcript is not the Claude
+ * Code JSONL that extractOutcome can parse, so capture the final assistant
+ * text as Cursor hands it to us. Fires once per assistant message; the last
+ * one before stop is the turn's outcome.
+ */
+async function onAgentResponse(input) {
+  const sessionId = sessionIdOf(input);
+  if (!sessionId || typeof input.text !== 'string' || !input.text.trim()) return;
+  const session = loadSession(sessionId);
+  session.outcome = input.text;
+  saveSession(sessionId, session);
 }
 
 function assistantText(entry) {
@@ -138,20 +162,25 @@ async function onStop(input) {
   // stop_hook_active means a stop hook already forced Claude to continue;
   // the real end of the turn will fire another Stop event.
   if (input.stop_hook_active) return;
-  if (!input.session_id || !input.transcript_path) return;
+  const sessionId = sessionIdOf(input);
+  if (!sessionId) return;
 
-  const session = loadSession(input.session_id);
+  const session = loadSession(sessionId);
   if (session.prompts.length === 0) return;
 
-  // Wait for the final assistant message to land in the transcript; on
-  // timeout fall back to the last text we did find (best effort).
-  const deadline = Date.now() + OUTCOME_SETTLE_TIMEOUT_MS;
-  let outcome;
-  for (;;) {
-    const { text, settled } = extractOutcome(input.transcript_path);
-    outcome = text;
-    if (settled || Date.now() >= deadline) break;
-    await sleep(OUTCOME_POLL_INTERVAL_MS);
+  // Cursor sessions get the outcome pushed to us via afterAgentResponse;
+  // Claude Code sessions read it from the transcript, waiting for the final
+  // assistant message to land there (on timeout, fall back to the last text
+  // we did find — best effort).
+  let outcome = session.outcome ?? null;
+  if (!outcome && input.transcript_path) {
+    const deadline = Date.now() + OUTCOME_SETTLE_TIMEOUT_MS;
+    for (;;) {
+      const { text, settled } = extractOutcome(input.transcript_path);
+      outcome = text;
+      if (settled || Date.now() >= deadline) break;
+      await sleep(OUTCOME_POLL_INTERVAL_MS);
+    }
   }
   if (!outcome) return;
 
@@ -167,8 +196,9 @@ async function onStop(input) {
     body: JSON.stringify({
       request: clamp(session.prompts.join('\n\n')),
       outcome: clamp(outcome),
-      session_id: input.session_id,
-      cwd: input.cwd ?? process.cwd(),
+      session_id: sessionId,
+      // Cursor sends workspace_roots instead of cwd.
+      cwd: input.cwd ?? input.workspace_roots?.[0] ?? process.cwd(),
     }),
     signal: AbortSignal.timeout(SEND_TIMEOUT_MS),
   });
@@ -176,7 +206,7 @@ async function onStop(input) {
     throw new Error(`POST /agent-activities failed: ${response.status}`);
   }
 
-  rmSync(sessionPath(input.session_id), { force: true });
+  rmSync(sessionPath(sessionId), { force: true });
 }
 
 const MAX_TASKS = 3;
@@ -195,6 +225,9 @@ async function onSessionStart(input) {
   // Compaction restarts the session mid-conversation; the tasks were
   // already offered, so don't show (or inject) them again.
   if (input.source === 'compact') return;
+  // Cursor also fires sessionStart for headless background agents — there is
+  // no user watching who could pick a task.
+  if (input.is_background_agent) return;
 
   const config = loadConfig();
   if (!config.token) return;
@@ -222,6 +255,36 @@ async function onSessionStart(input) {
     .slice(0, MAX_TASKS);
   if (tasks.length === 0) return;
 
+  const additionalContext =
+    `The user has Ari connected via ari-hooks. At session start the user was ` +
+    `shown this list of suggested tasks:\n\n` +
+    tasks
+      .map(
+        (t, i) =>
+          `Task ${i + 1}: ${oneLine(t.taskName)}\nPrompt: ${clamp(t.prompt)}`
+      )
+      .join('\n\n') +
+    `\n\nIf the user asks to run one of these tasks (by number or name), ` +
+    `carry out that task's prompt as if the user had typed it. Do not start ` +
+    `any of these tasks unless the user asks.`;
+
+  // Cursor's sessionStart output is a flat { additional_context } and it has
+  // no user-visible systemMessage channel, so the agent itself must surface
+  // the list.
+  if (isCursorInput(input)) {
+    writeSync(
+      1,
+      JSON.stringify({
+        additional_context:
+          additionalContext +
+          `\n\nNote: unlike Claude Code, Cursor did NOT show the user this ` +
+          `list — briefly offer these tasks by name at the start of your ` +
+          `first reply.`,
+      }) + '\n'
+    );
+    return;
+  }
+
   // Claude Code renders systemMessage with ANSI intact; the leading \n
   // pushes our block below the fixed "SessionStart:<source> says:" prefix.
   const BOLD = '\x1b[1m';
@@ -236,19 +299,6 @@ async function onSessionStart(input) {
     `${visibleList}\n` +
     `${GREY}Reply "run task 1" (or the task name) to start one.${RESET}`;
 
-  const additionalContext =
-    `The user has Ari connected via ari-hooks. At session start the user was ` +
-    `shown this list of suggested tasks:\n\n` +
-    tasks
-      .map(
-        (t, i) =>
-          `Task ${i + 1}: ${oneLine(t.taskName)}\nPrompt: ${clamp(t.prompt)}`
-      )
-      .join('\n\n') +
-    `\n\nIf the user asks to run one of these tasks (by number or name), ` +
-    `carry out that task's prompt as if the user had typed it. Do not start ` +
-    `any of these tasks unless the user asks.`;
-
   // writeSync: process.exit(0) in runHook would race an async stdout write.
   writeSync(
     1,
@@ -273,6 +323,8 @@ export async function runHook(event) {
     const input = raw ? JSON.parse(raw) : {};
     if (event === 'user-prompt-submit') {
       await onUserPromptSubmit(input);
+    } else if (event === 'agent-response') {
+      await onAgentResponse(input);
     } else if (event === 'stop') {
       await onStop(input);
     } else if (event === 'session-start') {

package/src/init.js

@@ -1,5 +1,7 @@
-import { join } from 'node:path';
+import { dirname, join } from 'node:path';
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { createInterface } from 'node:readline/promises';
 
 const HOOK_EVENTS = {
   SessionStart: 'ari-hooks hook session-start',
@@ -7,25 +9,77 @@ const HOOK_EVENTS = {
   Stop: 'ari-hooks hook stop',
 };
 
+// Cursor's agent doesn't read .claude/settings.json — it has its own hooks
+// system in .cursor/hooks.json with different event names and a flat entry
+// format. Cursor's transcript is not the Claude Code JSONL our stop handler
+// parses, so afterAgentResponse captures the final assistant text instead.
+const CURSOR_HOOK_EVENTS = {
+  sessionStart: 'ari-hooks hook session-start',
+  beforeSubmitPrompt: 'ari-hooks hook user-prompt-submit',
+  afterAgentResponse: 'ari-hooks hook agent-response',
+  stop: 'ari-hooks hook stop',
+};
+
+// Cursor's app install shows up in the env vars its integrated terminal
+// inherits: the git-askpass helpers point into Cursor.app (macOS),
+// AppData\Local\Programs\cursor (Windows), or a cursor install dir (Linux).
+const CURSOR_PATH_VARS = [
+  'GIT_ASKPASS',
+  'VSCODE_GIT_ASKPASS_NODE',
+  'VSCODE_GIT_ASKPASS_MAIN',
+];
+
+// Cursor ships via ToDesktop, so its macOS bundle id is this opaque token
+// rather than anything containing "cursor".
+const CURSOR_BUNDLE_ID = 'com.todesktop.230313mzl4w4u92';
+
 /**
- * Merge the ari-hooks hook commands into the project's Claude Code
- * settings (.claude/settings.json in cwd). Idempotent: existing ari-hooks
- * entries are left alone, and unrelated hooks/settings are preserved.
+ * Cursor's agent terminals export CURSOR_TRACE_ID and its CLI agent exports
+ * CURSOR_AGENT, but a regular integrated terminal in Cursor sets neither —
+ * it looks like VS Code (TERM_PROGRAM=vscode). There, the tells are the
+ * app's bundle id and the helper paths pointing into the Cursor install;
+ * plain VS Code and a bare shell match none of these.
  */
-export function init(cwd = process.cwd()) {
-  const claudeDir = join(cwd, '.claude');
-  const settingsPath = join(claudeDir, 'settings.json');
+export const isCursor = (env = process.env) =>
+  Boolean(
+    env.CURSOR_TRACE_ID ||
+      env.CURSOR_AGENT ||
+      env.__CFBundleIdentifier === CURSOR_BUNDLE_ID ||
+      CURSOR_PATH_VARS.some((key) => /cursor/i.test(env[key] ?? ''))
+  );
 
-  let settings = {};
+function readJson(path) {
   try {
-    settings = JSON.parse(readFileSync(settingsPath, 'utf8'));
+    return JSON.parse(readFileSync(path, 'utf8'));
   } catch (err) {
-    if (err.code !== 'ENOENT') {
-      throw new Error(
-        `${settingsPath} exists but is not valid JSON — fix or remove it, then re-run.`
-      );
-    }
+    if (err.code === 'ENOENT') return null;
+    throw new Error(
+      `${path} exists but is not valid JSON — fix or remove it, then re-run.`
+    );
   }
+}
+
+const writeJson = (path, value) =>
+  writeFileSync(path, JSON.stringify(value, null, 2) + '\n');
+
+/**
+ * Where the Claude Code hooks land, by scope:
+ *   project — ./.claude/settings.json        (shared with everyone on the repo)
+ *   local   — ./.claude/settings.local.json  (just this user; Claude Code
+ *             gitignores it)
+ *   user    — ~/.claude/settings.json        (every repo on this machine;
+ *             honors CLAUDE_CONFIG_DIR like Claude Code does)
+ */
+function claudeSettingsPath(scope, cwd, env) {
+  if (scope === 'user') {
+    return join(env.CLAUDE_CONFIG_DIR || join(homedir(), '.claude'), 'settings.json');
+  }
+  const file = scope === 'local' ? 'settings.local.json' : 'settings.json';
+  return join(cwd, '.claude', file);
+}
+
+function initClaude(settingsPath) {
+  const settings = readJson(settingsPath) ?? {};
 
   settings.hooks ??= {};
   let changed = false;
@@ -44,39 +98,110 @@ export function init(cwd = process.cwd()) {
 
   if (!changed) {
     console.log(`Ari hooks already configured in ${settingsPath}`);
-    return;
+    return false;
   }
 
-  mkdirSync(claudeDir, { recursive: true });
-  writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n');
+  mkdirSync(dirname(settingsPath), { recursive: true });
+  writeJson(settingsPath, settings);
   console.log(`✓ Ari hooks added to ${settingsPath}`);
-  console.log(
-    'Claude Code sessions in this folder will now share each request and its outcome with Ari,'
-  );
-  console.log('and show suggested Ari tasks when a session starts.');
+  return true;
 }
 
-/**
- * Remove the ari-hooks hook commands that init/install added to the
- * project's Claude Code settings. The inverse of init: only ari-hooks
- * entries are touched, everything else in the file is preserved.
- */
-export function uninstall(cwd = process.cwd()) {
-  const settingsPath = join(cwd, '.claude', 'settings.json');
+function initCursor(cwd) {
+  const cursorDir = join(cwd, '.cursor');
+  const hooksPath = join(cursorDir, 'hooks.json');
+  const config = readJson(hooksPath) ?? {};
 
-  if (!existsSync(settingsPath)) {
-    console.log(`No Claude Code settings found at ${settingsPath} — nothing to remove.`);
-    return;
+  config.version ??= 1;
+  config.hooks ??= {};
+  let changed = false;
+
+  for (const [event, command] of Object.entries(CURSOR_HOOK_EVENTS)) {
+    config.hooks[event] ??= [];
+    const already = config.hooks[event].some((h) =>
+      h.command?.includes('ari-hooks hook')
+    );
+    if (already) continue;
+    config.hooks[event].push({ command, timeout: 30 });
+    changed = true;
   }
 
-  let settings;
+  if (!changed) {
+    console.log(`Ari hooks already configured in ${hooksPath}`);
+    return false;
+  }
+
+  mkdirSync(cursorDir, { recursive: true });
+  writeJson(hooksPath, config);
+  console.log(`✓ Ari hooks added to ${hooksPath} (Cursor detected)`);
+  return true;
+}
+
+async function ask(question) {
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
   try {
-    settings = JSON.parse(readFileSync(settingsPath, 'utf8'));
+    return (await rl.question(question)).trim().toLowerCase();
   } catch {
-    throw new Error(
-      `${settingsPath} exists but is not valid JSON — fix or remove it, then re-run.`
-    );
+    // Ctrl+D / closed stdin — fall through to the question's default.
+    return '';
+  } finally {
+    rl.close();
   }
+}
+
+/**
+ * Interactive scope picker for the Claude Code hooks: repo-only or
+ * machine-wide, and — when repo-only — private (settings.local.json) or
+ * shared with everyone on the repo (settings.json).
+ */
+async function chooseClaudeScope() {
+  const repoOnly = await ask('Install hooks just for this repo? [Y/n] ');
+  if (repoOnly === 'n' || repoOnly === 'no') return 'user';
+
+  const who = await ask(
+    'Install just for yourself, or for everyone who works on this repo?\n' +
+      '  1) Just me   (.claude/settings.local.json, not committed)\n' +
+      '  2) Everyone  (.claude/settings.json, committed with the repo)\n' +
+      'Choose [1/2] (default 1): '
+  );
+  return who === '2' || who === 'everyone' ? 'project' : 'local';
+}
+
+/**
+ * Merge the ari-hooks hook commands into Claude Code settings — and, when
+ * running inside Cursor, into .cursor/hooks.json as well. Idempotent:
+ * existing ari-hooks entries are left alone, and unrelated hooks/settings
+ * are preserved. `scope` picks the Claude settings file (see
+ * claudeSettingsPath); the Cursor hooks file is always project-level.
+ */
+export function init(cwd = process.cwd(), env = process.env, scope = 'project') {
+  const changedClaude = initClaude(claudeSettingsPath(scope, cwd, env));
+  const changedCursor = isCursor(env) ? initCursor(cwd) : false;
+
+  if (!changedClaude && !changedCursor) return;
+  const where = scope === 'user' ? 'on this machine' : 'in this folder';
+  console.log(
+    `Agent sessions ${where} will now share each request and its outcome with Ari,`
+  );
+  console.log('and show suggested Ari tasks when a session starts.');
+}
+
+/**
+ * The `install` flavor of init: when attached to a terminal, ask where the
+ * Claude Code hooks should live before writing them. Non-interactive runs
+ * (CI, piped stdin) keep the old default of ./.claude/settings.json.
+ */
+export async function install(cwd = process.cwd(), env = process.env) {
+  const scope =
+    process.stdin.isTTY && process.stdout.isTTY
+      ? await chooseClaudeScope()
+      : 'project';
+  init(cwd, env, scope);
+}
+
+function uninstallClaude(settingsPath) {
+  if (!existsSync(settingsPath)) return false;
+  const settings = readJson(settingsPath);
 
   const isOurs = (h) => h.command?.includes('ari-hooks hook');
   let changed = false;
@@ -95,18 +220,60 @@ export function uninstall(cwd = process.cwd()) {
     else delete settings.hooks[event];
   }
 
-  if (!changed) {
-    console.log(`No Ari hooks found in ${settingsPath} — nothing to remove.`);
-    return;
-  }
+  if (!changed) return false;
 
   if (settings.hooks && Object.keys(settings.hooks).length === 0) {
     delete settings.hooks;
   }
 
-  writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n');
+  writeJson(settingsPath, settings);
   console.log(`✓ Ari hooks removed from ${settingsPath}`);
+  return true;
+}
+
+function uninstallCursor(cwd) {
+  const hooksPath = join(cwd, '.cursor', 'hooks.json');
+  if (!existsSync(hooksPath)) return false;
+  const config = readJson(hooksPath);
+
+  const isOurs = (h) => h.command?.includes('ari-hooks hook');
+  let changed = false;
+
+  for (const [event, entries] of Object.entries(config.hooks ?? {})) {
+    if (!Array.isArray(entries)) continue;
+    const kept = entries.filter((h) => !isOurs(h));
+    if (kept.length === entries.length) continue;
+    changed = true;
+    if (kept.length > 0) config.hooks[event] = kept;
+    else delete config.hooks[event];
+  }
+
+  if (!changed) return false;
+
+  writeJson(hooksPath, config);
+  console.log(`✓ Ari hooks removed from ${hooksPath}`);
+  return true;
+}
+
+/**
+ * Remove the ari-hooks hook commands that init/install added to the
+ * Claude Code settings and Cursor hooks file. The inverse of init: only
+ * ari-hooks entries are touched, everything else in the files is
+ * preserved. Cleans every location install can write to (project
+ * settings.json, settings.local.json, the user-level settings, and the
+ * Cursor hooks file), so hooks don't linger wherever they were put.
+ */
+export function uninstall(cwd = process.cwd(), env = process.env) {
+  const removedClaude = ['project', 'local', 'user']
+    .map((scope) => uninstallClaude(claudeSettingsPath(scope, cwd, env)))
+    .some(Boolean);
+  const removedCursor = uninstallCursor(cwd);
+
+  if (!removedClaude && !removedCursor) {
+    console.log('No Ari hooks found in this folder — nothing to remove.');
+    return;
+  }
   console.log(
-    'Claude Code sessions in this folder will no longer share activity with Ari.'
+    'Agent sessions in this folder will no longer share activity with Ari.'
   );
 }