@ariso-ai/ari-hooks 0.1.0

package/README.md

@@ -0,0 +1,69 @@
+# ari-hooks
+
+Shares your Claude Code activity with [Ari](https://ariso.ai): after every
+Claude Code turn, the hooks send your request and the final outcome (not the
+intermediate steps) to Ari.
+
+## Install
+
+```bash
+npm install -g ari-hooks
+```
+
+## Use
+
+In any project folder where you use Claude Code:
+
+```bash
+ari-hooks
+```
+
+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 two hooks to `./.claude/settings.json`:
+   - `UserPromptSubmit` — records what you asked for
+   - `Stop` — reads the final assistant message from the transcript and sends
+     the request/outcome pair to the Ari API
+
+Existing settings and hooks are preserved; running it again is a no-op.
+
+### Commands
+
+| Command | What it does |
+|---|---|
+| `ari-hooks` | Login (if needed) + set up hooks in the current folder |
+| `ari-hooks login` | Browser login, stores the API token |
+| `ari-hooks init` | Just add the hooks to `./.claude/settings.json` |
+| `ari-hooks config` | Show configured URLs and login state |
+| `ari-hooks status` | Show login state |
+| `ari-hooks logout` | Delete the stored token |
+
+### Configuration
+
+By default the CLI talks to production (`https://web.ari.ariso.ai` /
+`https://api.ari.ariso.ai`). To test against a local Ari stack, persist
+overrides with the URL flags (they work on any command, including bare
+`ari-hooks`):
+
+```bash
+ari-hooks config --web-url http://localhost:5173 --api-url http://localhost:4000
+ari-hooks login                # browser flow now goes through localhost
+ari-hooks config --reset-urls  # back to production
+```
+
+The overrides are stored in `~/.ari-hooks/config.json`, so the hooks
+themselves also report to the configured API. Environment variables take
+precedence over the stored config:
+
+- `ARI_HOOKS_API_URL` — override the API base URL
+- `ARI_HOOKS_WEB_URL` — override the web app URL used for login
+- `ARI_HOOKS_HOME` — override the config directory (default `~/.ari-hooks`)
+
+## Notes
+
+- Hooks never break your Claude Code session: every failure is swallowed and
+  logged to `~/.ari-hooks/error.log`.
+- Only the request text and the final assistant message are sent — no tool
+  calls, diffs, or intermediate steps.

package/bin/ari-hooks.js

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+import { main } from '../src/cli.js';
+
+main(process.argv.slice(2)).catch((err) => {
+  console.error(err?.message ?? err);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@ariso-ai/ari-hooks",
+  "version": "0.1.0",
+  "description": "Set up Claude Code hooks that share your requests and their outcomes with Ari",
+  "type": "module",
+  "bin": {
+    "ari-hooks": "bin/ari-hooks.js"
+  },
+  "files": [
+    "bin",
+    "src"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "test": "node --test"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "claude-code",
+    "hooks",
+    "ari",
+    "ariso"
+  ],
+  "license": "UNLICENSED"
+}

package/src/cli.js

@@ -0,0 +1,87 @@
+import { login, logout, status } from './login.js';
+import { init } 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              Log in (if needed) and set up hooks in the current folder
+  ari-hooks login        Log in via the browser and store an API token
+  ari-hooks init         Add the hooks to ./.claude/settings.json
+  ari-hooks config       Show the configured URLs and login state
+  ari-hooks status       Show login state
+  ari-hooks logout       Remove the stored token
+
+Options (persisted to ~/.ari-hooks/config.json, work with any command):
+  --web-url <url>        Set the Ari web app URL, e.g. http://localhost:5173
+  --api-url <url>        Set the Ari API URL, e.g. http://localhost:4000
+  --reset-urls           Go back to the default production URLs
+  -h, --help             Show this help
+
+The ARI_HOOKS_WEB_URL / ARI_HOOKS_API_URL environment variables take
+precedence over the persisted config.
+`;
+
+function parseFlags(args) {
+  const flags = {};
+  const rest = [];
+  for (let i = 0; i < args.length; i++) {
+    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 rest.push(args[i]);
+  }
+  return { flags, rest };
+}
+
+export async function main(argv) {
+  const { flags, rest } = parseFlags(argv);
+  const command = rest[0];
+
+  if (command === '-h' || command === '--help' || command === 'help') {
+    console.log(USAGE);
+    return;
+  }
+
+  // Persist URL overrides before dispatching so they apply to this run and
+  // every later hook invocation, regardless of which command they rode in on.
+  if (flags.webUrl || flags.apiUrl || flags.resetUrls) {
+    setUrls(flags);
+  }
+
+  switch (command) {
+    case 'login':
+      await login();
+      return;
+    case 'logout':
+      logout();
+      return;
+    case 'status':
+      status();
+      return;
+    case 'config':
+      showConfig();
+      return;
+    case 'init':
+      init();
+      return;
+    case 'hook':
+      await runHook(rest[1]);
+      return;
+    case undefined: {
+      // Bare invocation: make "npx/global install → run once in a folder"
+      // the whole setup story. URL-only invocations (e.g. `ari-hooks
+      // --web-url ...`) still run the full setup with the new URLs.
+      if (!loadConfig().token) {
+        await login();
+      }
+      init();
+      return;
+    }
+    default:
+      console.error(`Unknown command: ${command}\n`);
+      console.log(USAGE);
+      process.exitCode = 1;
+  }
+}

package/src/config.js

@@ -0,0 +1,78 @@
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { mkdirSync, readFileSync, writeFileSync, rmSync } from 'node:fs';
+
+export const DEFAULT_WEB_URL = 'https://web.ari.ariso.ai';
+export const DEFAULT_API_URL = 'https://api.ari.ariso.ai';
+
+export const configDir = () =>
+  process.env.ARI_HOOKS_HOME || join(homedir(), '.ari-hooks');
+
+const configPath = () => join(configDir(), 'config.json');
+
+export function loadConfig() {
+  try {
+    return JSON.parse(readFileSync(configPath(), 'utf8'));
+  } catch {
+    return {};
+  }
+}
+
+export function saveConfig(config) {
+  mkdirSync(configDir(), { recursive: true, mode: 0o700 });
+  writeFileSync(configPath(), JSON.stringify(config, null, 2) + '\n', {
+    mode: 0o600,
+  });
+}
+
+export function clearConfig() {
+  rmSync(configPath(), { force: true });
+}
+
+export function getApiUrl(config = loadConfig()) {
+  return process.env.ARI_HOOKS_API_URL || config.apiUrl || DEFAULT_API_URL;
+}
+
+export function getWebUrl(config = loadConfig()) {
+  return process.env.ARI_HOOKS_WEB_URL || config.webUrl || DEFAULT_WEB_URL;
+}
+
+function normalizeUrl(raw, label) {
+  let url;
+  try {
+    url = new URL(raw);
+  } catch {
+    throw new Error(`${label} is not a valid URL: ${raw}`);
+  }
+  if (url.protocol !== 'http:' && url.protocol !== 'https:') {
+    throw new Error(`${label} must be http(s): ${raw}`);
+  }
+  return url.toString().replace(/\/$/, '');
+}
+
+/** Persist base-URL overrides (e.g. point at localhost for testing). */
+export function setUrls({ webUrl, apiUrl, resetUrls }) {
+  const config = loadConfig();
+  if (resetUrls) {
+    delete config.webUrl;
+    delete config.apiUrl;
+  }
+  if (webUrl) config.webUrl = normalizeUrl(webUrl, '--web-url');
+  if (apiUrl) config.apiUrl = normalizeUrl(apiUrl, '--api-url');
+  saveConfig(config);
+  console.log(`Web URL: ${getWebUrl(config)}`);
+  console.log(`API URL: ${getApiUrl(config)}`);
+}
+
+export function showConfig() {
+  const config = loadConfig();
+  const note = (key, envVar) =>
+    process.env[envVar]
+      ? ` (from ${envVar})`
+      : config[key]
+        ? ' (configured)'
+        : ' (default)';
+  console.log(`Web URL: ${getWebUrl(config)}${note('webUrl', 'ARI_HOOKS_WEB_URL')}`);
+  console.log(`API URL: ${getApiUrl(config)}${note('apiUrl', 'ARI_HOOKS_API_URL')}`);
+  console.log(config.token ? `Logged in (since ${config.loggedInAt ?? 'unknown'})` : 'Not logged in.');
+}

package/src/hooks.js

@@ -0,0 +1,149 @@
+import { join } from 'node:path';
+import {
+  mkdirSync,
+  readFileSync,
+  writeFileSync,
+  rmSync,
+  appendFileSync,
+} from 'node:fs';
+import { configDir, loadConfig, getApiUrl } from './config.js';
+
+const MAX_TEXT_LENGTH = 100_000;
+const SEND_TIMEOUT_MS = 15_000;
+
+const sessionsDir = () => join(configDir(), 'sessions');
+const sessionPath = (sessionId) =>
+  join(sessionsDir(), `${sessionId.replace(/[^a-zA-Z0-9_-]/g, '_')}.json`);
+
+function readStdin() {
+  return new Promise((resolve) => {
+    let data = '';
+    process.stdin.setEncoding('utf8');
+    process.stdin.on('data', (chunk) => (data += chunk));
+    process.stdin.on('end', () => resolve(data));
+  });
+}
+
+function logError(err) {
+  try {
+    mkdirSync(configDir(), { recursive: true });
+    appendFileSync(
+      join(configDir(), 'error.log'),
+      `${new Date().toISOString()} ${err?.stack ?? err}\n`
+    );
+  } catch {
+    // Never let diagnostics break a hook.
+  }
+}
+
+function loadSession(sessionId) {
+  try {
+    return JSON.parse(readFileSync(sessionPath(sessionId), 'utf8'));
+  } catch {
+    return { prompts: [] };
+  }
+}
+
+function saveSession(sessionId, session) {
+  mkdirSync(sessionsDir(), { recursive: true });
+  writeFileSync(sessionPath(sessionId), JSON.stringify(session));
+}
+
+/**
+ * UserPromptSubmit: remember the prompt so the Stop hook can pair it with
+ * the turn's outcome.
+ */
+async function onUserPromptSubmit(input) {
+  if (!input.session_id || typeof input.prompt !== 'string') return;
+  const session = loadSession(input.session_id);
+  session.prompts.push(input.prompt);
+  saveSession(input.session_id, session);
+}
+
+/**
+ * Pull the final assistant text out of the transcript (JSONL). This is the
+ * "outcome" — we deliberately skip the intermediate steps/tool calls.
+ */
+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;
+    try {
+      entry = JSON.parse(lines[i]);
+    } catch {
+      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;
+  }
+  return null;
+}
+
+const clamp = (text) =>
+  text.length > MAX_TEXT_LENGTH ? text.slice(0, MAX_TEXT_LENGTH) : 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) {
+  // 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 session = loadSession(input.session_id);
+  if (session.prompts.length === 0) return;
+
+  const outcome = extractOutcome(input.transcript_path);
+  if (!outcome) return;
+
+  const config = loadConfig();
+  if (!config.token) return;
+
+  const response = await fetch(new URL('/agent-activities', getApiUrl(config)), {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      Authorization: `Bearer ${config.token}`,
+    },
+    body: JSON.stringify({
+      request: clamp(session.prompts.join('\n\n')),
+      outcome: clamp(outcome),
+      session_id: input.session_id,
+      cwd: input.cwd ?? process.cwd(),
+    }),
+    signal: AbortSignal.timeout(SEND_TIMEOUT_MS),
+  });
+  if (!response.ok) {
+    throw new Error(`POST /agent-activities failed: ${response.status}`);
+  }
+
+  rmSync(sessionPath(input.session_id), { force: true });
+}
+
+/**
+ * Entry point for `ari-hooks hook <event>`. Hooks must never break the
+ * 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) {
+  try {
+    const raw = await readStdin();
+    const input = raw ? JSON.parse(raw) : {};
+    if (event === 'user-prompt-submit') {
+      await onUserPromptSubmit(input);
+    } else if (event === 'stop') {
+      await onStop(input);
+    }
+  } catch (err) {
+    logError(err);
+  }
+  process.exit(0);
+}

package/src/init.js

@@ -0,0 +1,55 @@
+import { join } from 'node:path';
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+
+const HOOK_EVENTS = {
+  UserPromptSubmit: 'ari-hooks hook user-prompt-submit',
+  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.
+ */
+export function init(cwd = process.cwd()) {
+  const claudeDir = join(cwd, '.claude');
+  const settingsPath = join(claudeDir, 'settings.json');
+
+  let settings = {};
+  try {
+    settings = JSON.parse(readFileSync(settingsPath, 'utf8'));
+  } catch (err) {
+    if (err.code !== 'ENOENT') {
+      throw new Error(
+        `${settingsPath} exists but is not valid JSON — fix or remove it, then re-run.`
+      );
+    }
+  }
+
+  settings.hooks ??= {};
+  let changed = false;
+
+  for (const [event, command] of Object.entries(HOOK_EVENTS)) {
+    settings.hooks[event] ??= [];
+    const already = settings.hooks[event].some((matcher) =>
+      (matcher.hooks ?? []).some((h) => h.command?.includes('ari-hooks hook'))
+    );
+    if (already) continue;
+    settings.hooks[event].push({
+      hooks: [{ type: 'command', command, timeout: 30 }],
+    });
+    changed = true;
+  }
+
+  if (!changed) {
+    console.log(`Ari hooks already configured in ${settingsPath}`);
+    return;
+  }
+
+  mkdirSync(claudeDir, { recursive: true });
+  writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n');
+  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.'
+  );
+}

package/src/login.js

@@ -0,0 +1,109 @@
+import { createServer } from 'node:http';
+import { randomBytes } from 'node:crypto';
+import { spawn } from 'node:child_process';
+import {
+  loadConfig,
+  saveConfig,
+  getWebUrl,
+  getApiUrl,
+  clearConfig,
+} from './config.js';
+
+const LOGIN_TIMEOUT_MS = 5 * 60 * 1000;
+
+const SUCCESS_HTML = `<!doctype html>
+<html><head><title>Ari Hooks</title></head>
+<body style="font-family: sans-serif; text-align: center; padding-top: 4rem;">
+<h2>✓ Logged in</h2>
+<p>The Ari Hooks CLI received your token. You can close this window.</p>
+</body></html>`;
+
+function openBrowser(url) {
+  const cmd =
+    process.platform === 'darwin'
+      ? 'open'
+      : process.platform === 'win32'
+        ? 'start'
+        : 'xdg-open';
+  const child = spawn(cmd, [url], {
+    stdio: 'ignore',
+    detached: true,
+    shell: process.platform === 'win32',
+  });
+  child.on('error', () => {});
+  child.unref();
+}
+
+/**
+ * Browser login: start a one-shot loopback HTTP server, send the user to
+ * the web app's /cli-auth page with our callback URL, and wait for the
+ * page to redirect back with a freshly minted API token.
+ */
+export async function login() {
+  const config = loadConfig();
+  const state = randomBytes(16).toString('hex');
+
+  const token = await new Promise((resolve, reject) => {
+    const server = createServer((req, res) => {
+      const url = new URL(req.url, 'http://127.0.0.1');
+      if (url.pathname !== '/callback') {
+        res.writeHead(404).end();
+        return;
+      }
+      if (url.searchParams.get('state') !== state) {
+        res.writeHead(400).end('State mismatch — please retry `ari-hooks login`.');
+        return;
+      }
+      const received = url.searchParams.get('token');
+      if (!received) {
+        res.writeHead(400).end('Missing token.');
+        return;
+      }
+      res.writeHead(200, { 'Content-Type': 'text/html' }).end(SUCCESS_HTML);
+      // Let the response flush before tearing the server down.
+      setTimeout(() => server.close(), 100);
+      resolve(received);
+    });
+
+    server.on('error', reject);
+    server.listen(0, '127.0.0.1', () => {
+      const { port } = server.address();
+      const authUrl = new URL('/cli-auth', getWebUrl(config));
+      authUrl.searchParams.set(
+        'callback',
+        `http://127.0.0.1:${port}/callback`
+      );
+      authUrl.searchParams.set('state', state);
+
+      console.log('Opening your browser to log in to Ari...');
+      console.log(`If it does not open, visit:\n\n  ${authUrl}\n`);
+      openBrowser(authUrl.toString());
+    });
+
+    setTimeout(() => {
+      server.close();
+      reject(new Error('Login timed out after 5 minutes. Please retry `ari-hooks login`.'));
+    }, LOGIN_TIMEOUT_MS).unref();
+  });
+
+  config.token = token;
+  config.loggedInAt = new Date().toISOString();
+  saveConfig(config);
+  console.log('✓ Logged in. Token saved to ~/.ari-hooks/config.json');
+  return token;
+}
+
+export function logout() {
+  clearConfig();
+  console.log('Logged out — local token removed.');
+}
+
+export function status() {
+  const config = loadConfig();
+  if (!config.token) {
+    console.log('Not logged in. Run `ari-hooks login`.');
+    return;
+  }
+  console.log(`Logged in (since ${config.loggedInAt ?? 'unknown'})`);
+  console.log(`API: ${getApiUrl(config)}`);
+}