@ariso-ai/ari-hooks 0.1.7 → 0.1.9

package/README.md

@@ -24,7 +24,11 @@ That single command:
 
 1. Opens your browser to log in to Ari and mint an API token (stored in
    `~/.ari-hooks/config.json`, `0600`). Only needed once per machine.
-2. Adds three hooks to `./.claude/settings.json`:
+2. Detects which coding agents you use — Claude Code, Codex, and Cursor — and
+   wires up the hooks for each one it finds (Claude Code by `~/.claude`, Codex
+   by `~/.codex`, Cursor by the environment variables it sets in its terminal).
+   If it can't tell, it defaults to Claude Code.
+3. For Claude Code, adds three hooks to `./.claude/settings.json`:
    - `SessionStart` — fetches Ari's top suggested tasks and shows them when
      Claude Code boots; reply with a task number or name to run one
    - `UserPromptSubmit` — records what you asked for
@@ -33,6 +37,21 @@ That single command:
 
 Existing settings and hooks are preserved; running it again is a no-op.
 
+### Codex
+
+Codex reads hooks from `.codex/hooks.json` (project) or `~/.codex/hooks.json`
+(machine-wide), using the same nested shape as Claude Code. When `ari-hooks
+install` (or `init`) detects Codex, it writes the two activity-sharing hooks
+there:
+
+- `UserPromptSubmit` — records what you asked for
+- `Stop` — Codex hands the final assistant text to the hook directly (as
+  `last_assistant_message`), and that request/outcome pair is sent to the Ari
+  API
+
+Codex has no user-visible channel to render Ari's suggested-task list, so the
+`SessionStart` task prompt is skipped there.
+
 ### Cursor
 
 Cursor's agent doesn't read `.claude/settings.json` — it has its own hooks
@@ -48,14 +67,15 @@ writes the equivalent hooks there:
   this event instead)
 - `stop` — sends the request/outcome pair to the Ari API
 
-`ari-hooks uninstall` cleans up both files, wherever it runs.
+`ari-hooks uninstall` cleans up every file — Claude Code, Codex, and Cursor —
+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 install` | Login (if needed) + detect your agents and set up their hooks in the current folder |
+| `ari-hooks uninstall` | Remove the hooks from the Claude Code, Codex (`./.codex/hooks.json`, `~/.codex/hooks.json`), and Cursor files |
 | `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 |
@@ -88,3 +108,7 @@ precedence over the stored config:
   logged to `~/.ari-hooks/error.log`.
 - Only the request text and the final assistant message are sent — no tool
   calls, diffs, or intermediate steps.
+
+## Author
+
+Max Heckel

package/package.json

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

package/src/cli.js

@@ -6,13 +6,16 @@ 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; 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 install      Log in (if needed) and set up hooks. Detects which
+                         coding agents you use (Claude Code, Codex, Cursor) and
+                         wires up each one; 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. Codex hooks go in ./.codex/hooks.json (or
+                         ~/.codex/hooks.json), Cursor's in ./.cursor/hooks.json
   ari-hooks uninstall    Remove the hooks from ./.claude/settings.json,
                          ./.claude/settings.local.json, ~/.claude/settings.json,
+                         ./.codex/hooks.json, ~/.codex/hooks.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 (no login)
@@ -37,6 +40,7 @@ function parseFlags(args) {
     if (args[i] === '--web-url') flags.webUrl = args[++i];
     else if (args[i] === '--api-url') flags.apiUrl = args[++i];
     else if (args[i] === '--reset-urls') flags.resetUrls = true;
+    else if (args[i] === '--agent') flags.agent = args[++i];
     else rest.push(args[i]);
   }
   return { flags, rest };
@@ -84,7 +88,7 @@ export async function main(argv) {
       uninstall();
       return;
     case 'hook':
-      await runHook(rest[1]);
+      await runHook(rest[1], flags.agent);
       return;
     case undefined:
       // URL-only invocations (e.g. `ari-hooks --web-url ...`) are a

package/src/hooks.js

@@ -66,6 +66,41 @@ 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';
 
+// agent_type values, keyed by the --agent slug the hook command passes (init
+// bakes it into each agent's config file).
+const AGENT_TYPES = { claude: 'claude-code', codex: 'codex', cursor: 'cursor' };
+
+// Which coding agent produced this turn. The --agent flag from the hook command
+// is the reliable source; fall back to sniffing the payload for installs that
+// predate the flag — Cursor stamps cursor_version, Claude Code sends a
+// transcript_path, and Codex has neither (it hands us last_assistant_message).
+function agentTypeOf(input, agent) {
+  if (AGENT_TYPES[agent]) return AGENT_TYPES[agent];
+  if (isCursorInput(input)) return 'cursor';
+  if (input.transcript_path) return 'claude-code';
+  return 'codex';
+}
+
+// Claude Code auto-delivers a background task's completion as a synthetic
+// UserPromptSubmit turn — the entire prompt is a <task-notification> block,
+// not something the user typed. Recording it verbatim as a "request"
+// pollutes the activity feed with agent-internal bookkeeping, so swap it for
+// a short human-readable stand-in built from the notification's <summary>.
+const TASK_NOTIFICATION_RE = /^<task-notification>[\s\S]*<\/task-notification>$/;
+const SUMMARY_RE = /<summary>([\s\S]*?)<\/summary>/;
+const XML_ENTITIES = { amp: '&', lt: '<', gt: '>', quot: '"', apos: "'" };
+const decodeXmlEntities = (text) =>
+  text.replace(/&(amp|lt|gt|quot|apos);/g, (_, name) => XML_ENTITIES[name]);
+
+function taskNotificationStandIn(prompt) {
+  const trimmed = prompt.trim();
+  if (!TASK_NOTIFICATION_RE.test(trimmed)) return null;
+  const summary = trimmed.match(SUMMARY_RE)?.[1]?.trim();
+  return summary
+    ? `The coding agent ran a background task: ${decodeXmlEntities(summary)}`
+    : 'The coding agent ran a background task.';
+}
+
 /**
  * UserPromptSubmit (Claude Code) / beforeSubmitPrompt (Cursor): remember the
  * prompt so the Stop hook can pair it with the turn's outcome. Both hosts
@@ -75,7 +110,7 @@ async function onUserPromptSubmit(input) {
   const sessionId = sessionIdOf(input);
   if (!sessionId || typeof input.prompt !== 'string') return;
   const session = loadSession(sessionId);
-  session.prompts.push(input.prompt);
+  session.prompts.push(taskNotificationStandIn(input.prompt) ?? input.prompt);
   saveSession(sessionId, session);
 }
 
@@ -158,7 +193,7 @@ const clamp = (text) =>
  * Stop: the turn is over — send the accumulated request(s) plus the final
  * assistant message to Ari, then clear the per-session state.
  */
-async function onStop(input) {
+async function onStop(input, agent) {
   // 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;
@@ -168,11 +203,12 @@ async function onStop(input) {
   const session = loadSession(sessionId);
   if (session.prompts.length === 0) return;
 
-  // 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;
+  // Cursor sessions get the outcome pushed to us via afterAgentResponse; Codex
+  // hands us the final text directly on the Stop payload as
+  // last_assistant_message; 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 ?? input.last_assistant_message ?? null;
   if (!outcome && input.transcript_path) {
     const deadline = Date.now() + OUTCOME_SETTLE_TIMEOUT_MS;
     for (;;) {
@@ -197,6 +233,7 @@ async function onStop(input) {
       request: clamp(session.prompts.join('\n\n')),
       outcome: clamp(outcome),
       session_id: sessionId,
+      agent_type: agentTypeOf(input, agent),
       // Cursor sends workspace_roots instead of cwd.
       cwd: input.cwd ?? input.workspace_roots?.[0] ?? process.cwd(),
     }),
@@ -317,7 +354,7 @@ async function onSessionStart(input) {
  * user's Claude Code session: all failures are swallowed (logged to
  * ~/.ari-hooks/error.log) and we always exit 0.
  */
-export async function runHook(event) {
+export async function runHook(event, agent) {
   try {
     const raw = await readStdin();
     const input = raw ? JSON.parse(raw) : {};
@@ -326,7 +363,7 @@ export async function runHook(event) {
     } else if (event === 'agent-response') {
       await onAgentResponse(input);
     } else if (event === 'stop') {
-      await onStop(input);
+      await onStop(input, agent);
     } else if (event === 'session-start') {
       await onSessionStart(input);
     }

package/src/init.js

@@ -1,12 +1,28 @@
 import { dirname, join } from 'node:path';
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { createInterface } from 'node:readline/promises';
 
+// Each command carries an --agent flag so the Stop hook can report which coding
+// agent produced the activity (agent_name) without having to guess from the
+// payload — the config file it lives in is the reliable source of that fact.
 const HOOK_EVENTS = {
-  SessionStart: 'ari-hooks hook session-start',
-  UserPromptSubmit: 'ari-hooks hook user-prompt-submit',
-  Stop: 'ari-hooks hook stop',
+  SessionStart: 'ari-hooks hook session-start --agent claude',
+  UserPromptSubmit: 'ari-hooks hook user-prompt-submit --agent claude',
+  Stop: 'ari-hooks hook stop --agent claude',
+};
+
+// Codex copied Claude Code's hooks design: the same { hooks: { Event: [{ hooks:
+// [{ type, command }] }] } } shape and the same event names, read from
+// .codex/hooks.json (or ~/.codex/hooks.json). We only wire up the
+// activity-sharing pair: UserPromptSubmit remembers the prompt and Stop ships
+// the outcome (Codex hands us the final text on the Stop payload as
+// last_assistant_message — no transcript to parse; see onStop). We skip
+// SessionStart because Codex has no user-visible channel to render the
+// suggested-task list, so there is nothing to show.
+const CODEX_HOOK_EVENTS = {
+  UserPromptSubmit: 'ari-hooks hook user-prompt-submit --agent codex',
+  Stop: 'ari-hooks hook stop --agent codex',
 };
 
 // Cursor's agent doesn't read .claude/settings.json — it has its own hooks
@@ -14,10 +30,10 @@ const HOOK_EVENTS = {
 // 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',
+  sessionStart: 'ari-hooks hook session-start --agent cursor',
+  beforeSubmitPrompt: 'ari-hooks hook user-prompt-submit --agent cursor',
+  afterAgentResponse: 'ari-hooks hook agent-response --agent cursor',
+  stop: 'ari-hooks hook stop --agent cursor',
 };
 
 // Cursor's app install shows up in the env vars its integrated terminal
@@ -48,6 +64,37 @@ export const isCursor = (env = process.env) =>
       CURSOR_PATH_VARS.some((key) => /cursor/i.test(env[key] ?? ''))
   );
 
+const dirExists = (path) => {
+  try {
+    return statSync(path).isDirectory();
+  } catch {
+    return false;
+  }
+};
+
+// Each agent keeps its config under a home directory whose presence is the
+// tell that the user runs that agent; both honor the same env overrides the
+// agents themselves do (CLAUDE_CONFIG_DIR, CODEX_HOME), which also lets tests
+// point them at a scratch dir.
+const claudeHome = (env) => env.CLAUDE_CONFIG_DIR || join(homedir(), '.claude');
+const codexHome = (env) => env.CODEX_HOME || join(homedir(), '.codex');
+
+/**
+ * Which coding agents does this user run? Claude Code and Codex are detected by
+ * their config directory; Cursor by the marks it leaves in an integrated
+ * terminal (see isCursor). Returns a Set so install can branch to one config
+ * path per detected agent. Falls back to Claude Code when nothing is found so a
+ * fresh machine (or CI) still gets the primary target wired up.
+ */
+export function detectAgents(env = process.env) {
+  const agents = new Set();
+  if (dirExists(claudeHome(env))) agents.add('claude');
+  if (dirExists(codexHome(env))) agents.add('codex');
+  if (isCursor(env)) agents.add('cursor');
+  if (agents.size === 0) agents.add('claude');
+  return agents;
+}
+
 function readJson(path) {
   try {
     return JSON.parse(readFileSync(path, 'utf8'));
@@ -72,19 +119,36 @@ const writeJson = (path, value) =>
  */
 function claudeSettingsPath(scope, cwd, env) {
   if (scope === 'user') {
-    return join(env.CLAUDE_CONFIG_DIR || join(homedir(), '.claude'), 'settings.json');
+    return join(claudeHome(env), 'settings.json');
   }
   const file = scope === 'local' ? 'settings.local.json' : 'settings.json';
   return join(cwd, '.claude', file);
 }
 
-function initClaude(settingsPath) {
+// Codex has one project file and one user file — no committed/private split
+// like Claude Code's settings.local.json — so 'local' collapses onto the
+// project file.
+function codexHooksPath(scope, cwd, env) {
+  if (scope === 'user') {
+    return join(codexHome(env), 'hooks.json');
+  }
+  return join(cwd, '.codex', 'hooks.json');
+}
+
+/**
+ * Merge the ari-hooks commands into a settings file that uses the shared
+ * Claude Code / Codex nested hook shape ({ hooks: { Event: [{ hooks: [...] }] }
+ * }). Idempotent: an event that already has an ari-hooks command is left alone,
+ * everything else in the file is preserved. `label` tags the success line so
+ * the user can tell which agent a file belongs to.
+ */
+function initNestedHooks(settingsPath, events, label) {
   const settings = readJson(settingsPath) ?? {};
 
   settings.hooks ??= {};
   let changed = false;
 
-  for (const [event, command] of Object.entries(HOOK_EVENTS)) {
+  for (const [event, command] of Object.entries(events)) {
     settings.hooks[event] ??= [];
     const already = settings.hooks[event].some((matcher) =>
       (matcher.hooks ?? []).some((h) => h.command?.includes('ari-hooks hook'))
@@ -103,10 +167,15 @@ function initClaude(settingsPath) {
 
   mkdirSync(dirname(settingsPath), { recursive: true });
   writeJson(settingsPath, settings);
-  console.log(`✓ Ari hooks added to ${settingsPath}`);
+  console.log(`✓ Ari hooks added to ${settingsPath}${label ? ` (${label})` : ''}`);
   return true;
 }
 
+const initClaude = (settingsPath) => initNestedHooks(settingsPath, HOOK_EVENTS);
+
+const initCodex = (hooksPath) =>
+  initNestedHooks(hooksPath, CODEX_HOOK_EVENTS, 'Codex detected');
+
 function initCursor(cwd) {
   const cursorDir = join(cwd, '.cursor');
   const hooksPath = join(cursorDir, 'hooks.json');
@@ -168,17 +237,22 @@ async function chooseClaudeScope() {
 }
 
 /**
- * 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.
+ * Merge the ari-hooks hook commands into the config of every coding agent this
+ * user runs (see detectAgents): Claude Code settings, Codex hooks.json, and —
+ * inside Cursor — .cursor/hooks.json. Idempotent: existing ari-hooks entries
+ * are left alone, and unrelated hooks/settings are preserved. `scope` picks the
+ * Claude Code and Codex file (see claudeSettingsPath / codexHooksPath); 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 agents = detectAgents(env);
+  const changed = [
+    agents.has('claude') && initClaude(claudeSettingsPath(scope, cwd, env)),
+    agents.has('codex') && initCodex(codexHooksPath(scope, cwd, env)),
+    agents.has('cursor') && initCursor(cwd),
+  ];
+
+  if (!changed.some(Boolean)) 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,`
@@ -187,11 +261,14 @@ export function init(cwd = process.cwd(), env = process.env, scope = 'project')
 }
 
 /**
- * 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.
+ * The `install` flavor of init: report which agents were detected, and — when
+ * attached to a terminal — ask where the hooks should live before writing them.
+ * Non-interactive runs (CI, piped stdin) keep the old default of the
+ * project-level files.
  */
 export async function install(cwd = process.cwd(), env = process.env) {
+  const agents = detectAgents(env);
+  console.log(`Detected coding agent(s): ${[...agents].join(', ')}`);
   const scope =
     process.stdin.isTTY && process.stdout.isTTY
       ? await chooseClaudeScope()
@@ -199,7 +276,7 @@ export async function install(cwd = process.cwd(), env = process.env) {
   init(cwd, env, scope);
 }
 
-function uninstallClaude(settingsPath) {
+function uninstallNestedHooks(settingsPath) {
   if (!existsSync(settingsPath)) return false;
   const settings = readJson(settingsPath);
 
@@ -256,20 +333,24 @@ function uninstallCursor(cwd) {
 }
 
 /**
- * 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.
+ * Remove the ari-hooks hook commands that init/install added to the Claude
+ * Code settings, Codex hooks.json, 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 — regardless of which
+ * agents are currently detected — so hooks don't linger wherever they were put:
+ * the project/local/user Claude settings, the project and user Codex hooks, and
+ * the Cursor hooks file.
  */
 export function uninstall(cwd = process.cwd(), env = process.env) {
   const removedClaude = ['project', 'local', 'user']
-    .map((scope) => uninstallClaude(claudeSettingsPath(scope, cwd, env)))
+    .map((scope) => uninstallNestedHooks(claudeSettingsPath(scope, cwd, env)))
+    .some(Boolean);
+  const removedCodex = ['project', 'user']
+    .map((scope) => uninstallNestedHooks(codexHooksPath(scope, cwd, env)))
     .some(Boolean);
   const removedCursor = uninstallCursor(cwd);
 
-  if (!removedClaude && !removedCursor) {
+  if (!removedClaude && !removedCodex && !removedCursor) {
     console.log('No Ari hooks found in this folder — nothing to remove.');
     return;
   }