@ariso-ai/ari-hooks 0.1.4 → 0.1.6

package/README.md

@@ -33,11 +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` 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.4",
+  "version": "0.1.6",
   "description": "Set up Claude Code hooks that share your requests and their outcomes with Ari",
   "type": "module",
   "bin": {

package/src/cli.js

@@ -1,14 +1,21 @@
 import { login, logout, status } from './login.js';
-import { init } 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 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
@@ -67,12 +74,15 @@ export async function main(argv) {
       if (!loadConfig().token) {
         await login();
       }
-      init();
+      await install();
       return;
     }
     case 'init':
       init();
       return;
+    case 'uninstall':
+      uninstall();
+      return;
     case 'hook':
       await runHook(rest[1]);
       return;

package/src/hooks.js

@@ -11,6 +11,14 @@ import { configDir, loadConfig, getApiUrl } from './config.js';
 
 const MAX_TEXT_LENGTH = 100_000;
 const SEND_TIMEOUT_MS = 15_000;
+// Claude Code can fire Stop while the final assistant message is still being
+// flushed to the transcript; poll until the tail settles (or give up).
+const OUTCOME_POLL_INTERVAL_MS = 150;
+const OUTCOME_SETTLE_TIMEOUT_MS = Number(
+  process.env.ARI_HOOKS_SETTLE_TIMEOUT_MS ?? 5_000
+);
+
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 
 const sessionsDir = () => join(configDir(), 'sessions');
 const sessionPath = (sessionId) =>
@@ -50,40 +58,97 @@ 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) {
+  if (entry.type !== 'assistant' || !Array.isArray(entry.message?.content)) {
+    return '';
+  }
+  return entry.message.content
+    .filter((block) => block.type === 'text' && block.text)
+    .map((block) => block.text)
+    .join('\n')
+    .trim();
 }
 
 /**
  * Pull the final assistant text out of the transcript (JSONL). This is the
  * "outcome" — we deliberately skip the intermediate steps/tool calls.
+ *
+ * `settled` reports whether the exchange actually ends in assistant text.
+ * When the transcript instead ends at a tool call/result or a half-written
+ * line, the final message hasn't been flushed yet and `text` is only the
+ * last narration before a tool ran — the caller should re-read rather than
+ * ship that as the outcome.
  */
 function extractOutcome(transcriptPath) {
-  const lines = readFileSync(transcriptPath, 'utf8').split('\n');
-  for (let i = lines.length - 1; i >= 0; i--) {
-    if (!lines[i].trim()) continue;
-    let entry;
+  const entries = [];
+  let tailPartial = false;
+  for (const line of readFileSync(transcriptPath, 'utf8').split('\n')) {
+    if (!line.trim()) continue;
     try {
-      entry = JSON.parse(lines[i]);
+      entries.push(JSON.parse(line));
+      tailPartial = false;
     } catch {
+      tailPartial = true; // a line still being written
+    }
+  }
+
+  let settled = tailPartial ? false : null;
+  for (let i = entries.length - 1; i >= 0; i--) {
+    const entry = entries[i];
+    // Bookkeeping entries (system, attachment, last-prompt, …) may trail
+    // the exchange; they say nothing about whether it is complete.
+    if (entry.type !== 'assistant' && entry.type !== 'user') continue;
+    let text = assistantText(entry);
+    if (!text) {
+      // A tool call/result with nothing after it: mid-turn.
+      settled ??= false;
       continue;
     }
-    if (entry.type !== 'assistant' || !entry.message?.content) continue;
-    const text = entry.message.content
-      .filter((block) => block.type === 'text' && block.text)
-      .map((block) => block.text)
-      .join('\n')
-      .trim();
-    if (text) return text;
+    // The message may span several JSONL entries (one per content block);
+    // stitch earlier blocks of the same message back on.
+    const id = entry.message?.id;
+    for (let j = i - 1; id && j >= 0 && entries[j].message?.id === id; j--) {
+      const earlier = assistantText(entries[j]);
+      if (earlier) text = `${earlier}\n${text}`;
+    }
+    return { text, settled: settled ?? true };
   }
-  return null;
+  return { text: null, settled: false };
 }
 
 const clamp = (text) =>
@@ -97,12 +162,26 @@ 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;
 
-  const outcome = extractOutcome(input.transcript_path);
+  // 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;
 
   const config = loadConfig();
@@ -117,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),
   });
@@ -126,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;
@@ -145,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;
@@ -172,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';
@@ -186,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,
@@ -223,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 { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+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,56 @@ 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',
+};
+
 /**
- * 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 integrated terminal exports CURSOR_TRACE_ID and its CLI agent
+ * exports CURSOR_AGENT; neither is set by plain VS Code or a bare shell.
  */
-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);
 
-  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,14 +77,182 @@ 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}`);
+  return true;
+}
+
+function initCursor(cwd) {
+  const cursorDir = join(cwd, '.cursor');
+  const hooksPath = join(cursorDir, 'hooks.json');
+  const config = readJson(hooksPath) ?? {};
+
+  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;
+  }
+
+  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 {
+    return (await rl.question(question)).trim().toLowerCase();
+  } catch {
+    // 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(
-    'Claude Code sessions in this folder will now share each request and its outcome with Ari,'
+    `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;
+
+  for (const [event, matchers] of Object.entries(settings.hooks ?? {})) {
+    if (!Array.isArray(matchers)) continue;
+    const kept = matchers
+      .map((matcher) => {
+        if (!(matcher.hooks ?? []).some(isOurs)) return matcher;
+        changed = true;
+        const rest = matcher.hooks.filter((h) => !isOurs(h));
+        return rest.length > 0 ? { ...matcher, hooks: rest } : null;
+      })
+      .filter(Boolean);
+    if (kept.length > 0) settings.hooks[event] = kept;
+    else delete settings.hooks[event];
+  }
+
+  if (!changed) return false;
+
+  if (settings.hooks && Object.keys(settings.hooks).length === 0) {
+    delete settings.hooks;
+  }
+
+  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(
+    'Agent sessions in this folder will no longer share activity with Ari.'
+  );
+}