agenter-app 1.0.2 → 1.0.3

package/README.md

@@ -36,6 +36,7 @@ and keeps running in the background. Just open the window when you want it:
 | **Agenter shortcut** (Desktop / Start Menu / taskbar) | Opens the dashboard in its own app window and starts the server if needed. No console. |
 | `agenter` | Same thing, from a terminal. |
 | `agenter start` | Runs the server in the foreground with logs (handy for debugging). |
+| `agenter doctor` | Checks the hooks, port, Claude Code and login, and says how to fix anything that's wrong. Start here if sessions don't show up. |
 | `agenter shortcuts --startup` | Also starts the server silently when you log in to Windows. |
 
 Set `AGENTER_AUTOSTART=0` to stop hooks from starting the server.

package/cli.js

@@ -84,6 +84,7 @@ Usage: agenter [command]
   install          Add Agenter's hooks to ~/.claude/settings.json (backed up first)
                    and, on Windows, Desktop and Start Menu shortcuts
   uninstall        Remove the hooks and shortcuts
+  doctor           Check hooks, port, Claude Code and login, and say how to fix what's wrong
   start            Run the server in the foreground with logs
   shortcuts        (Re)create the Windows shortcuts; --startup also starts the server at login
   version          Print the version
@@ -107,6 +108,14 @@ After installing, reload your VS Code windows so Claude sessions pick up the hoo
     case 'start':
       status = node('server.js', rest);
       break;
+    case 'doctor': {
+      const { runChecks, format } = require('./lib/doctor');
+      const { findClaude, findCodex } = require('./server');
+      const results = await runChecks({ findClaude, findCodex });
+      console.log(format(results));
+      status = results.some((r) => r.status === 'fail') ? 1 : 0;
+      break;
+    }
     case 'shortcuts':
       status = shortcuts(rest.includes('--startup') ? ['-Startup'] : []);
       break;

package/install.js

@@ -10,18 +10,7 @@ const SETTINGS = path.join(os.homedir(), '.claude', 'settings.json');
 const HOOK_SCRIPT = path.join(__dirname, 'hook.js').replace(/\\/g, '/');
 const COMMAND = `node "${HOOK_SCRIPT}"`;
 
-// timeout is in seconds. Events that can wait for you get an hour.
-const EVENTS = {
-  SessionStart: { timeout: 10 },
-  SessionEnd: { timeout: 10 },
-  UserPromptSubmit: { timeout: 10 },
-  PreToolUse: { matcher: '*', timeout: 3600 },
-  PostToolUse: { matcher: '*', timeout: 10 },
-  PermissionRequest: { matcher: '*', timeout: 3600 },
-  Notification: { timeout: 10 },
-  Stop: { timeout: 3600 },
-  SubagentStop: { timeout: 10 },
-};
+const EVENTS = require('./lib/hook-events');
 
 const uninstall = process.argv.includes('--uninstall');
 

package/lib/diff.js

@@ -0,0 +1,126 @@
+'use strict';
+// Line diffs for the file changes Claude asks permission for (Edit, MultiEdit, Write).
+// Built on the server so the dashboard only has to draw rows, and so it can be tested.
+const fs = require('node:fs');
+const path = require('node:path');
+
+const CONTEXT = 3; // unchanged lines kept around each change
+const MAX_ROWS = 300; // rows sent per file; the rest is summarised
+const MAX_FILE_BYTES = 512 * 1024; // bigger files aren't read to diff a Write against
+const MAX_CELLS = 1_500_000; // LCS table size; beyond this fall back to "all replaced"
+
+const lines = (text) => {
+  text = String(text ?? '').replace(/\r\n/g, '\n');
+  return text === '' ? [] : text.split('\n');
+};
+
+// Ops: { type: 'ctx' | 'del' | 'add', text }. Common start and end are peeled off first,
+// so the usual small edit in a big block costs almost nothing.
+function lineDiff(oldText, newText) {
+  const a = lines(oldText);
+  const b = lines(newText);
+  let head = 0;
+  while (head < a.length && head < b.length && a[head] === b[head]) head++;
+  let tail = 0;
+  while (tail < a.length - head && tail < b.length - head && a[a.length - 1 - tail] === b[b.length - 1 - tail]) tail++;
+
+  const ops = [];
+  for (let i = 0; i < head; i++) ops.push({ type: 'ctx', text: a[i] });
+  const am = a.slice(head, a.length - tail);
+  const bm = b.slice(head, b.length - tail);
+  middle(am, bm, ops);
+  for (let i = a.length - tail; i < a.length; i++) ops.push({ type: 'ctx', text: a[i] });
+  return ops;
+}
+
+function middle(a, b, ops) {
+  const n = a.length;
+  const m = b.length;
+  if (!n || !m || (n + 1) * (m + 1) > MAX_CELLS) {
+    for (const text of a) ops.push({ type: 'del', text });
+    for (const text of b) ops.push({ type: 'add', text });
+    return;
+  }
+  // dp[i][j] = length of the longest common subsequence of a[i..] and b[j..]
+  const w = m + 1;
+  const dp = new Uint32Array((n + 1) * w);
+  for (let i = n - 1; i >= 0; i--) {
+    for (let j = m - 1; j >= 0; j--) {
+      dp[i * w + j] = a[i] === b[j] ? dp[(i + 1) * w + j + 1] + 1 : Math.max(dp[(i + 1) * w + j], dp[i * w + j + 1]);
+    }
+  }
+  let i = 0;
+  let j = 0;
+  while (i < n && j < m) {
+    if (a[i] === b[j]) ops.push({ type: 'ctx', text: a[i++] }), j++;
+    else if (dp[(i + 1) * w + j] >= dp[i * w + j + 1]) ops.push({ type: 'del', text: a[i++] });
+    else ops.push({ type: 'add', text: b[j++] });
+  }
+  while (i < n) ops.push({ type: 'del', text: a[i++] });
+  while (j < m) ops.push({ type: 'add', text: b[j++] });
+}
+
+// Keeps changes plus `context` lines around them; long unchanged runs become one
+// { type: 'skip', count } row. Rows past `maxRows` become { type: 'more', count }.
+function compact(ops, context = CONTEXT, maxRows = MAX_ROWS) {
+  const keep = new Array(ops.length).fill(false);
+  ops.forEach((op, i) => {
+    if (op.type === 'ctx') return;
+    for (let k = Math.max(0, i - context); k <= Math.min(ops.length - 1, i + context); k++) keep[k] = true;
+  });
+  const rows = [];
+  let skipped = 0;
+  const flush = () => {
+    if (skipped) rows.push({ type: 'skip', count: skipped });
+    skipped = 0;
+  };
+  ops.forEach((op, i) => {
+    if (keep[i]) (flush(), rows.push(op));
+    else skipped++;
+  });
+  flush();
+  if (rows.length <= maxRows) return rows;
+  const omitted = rows.slice(maxRows).reduce((n, r) => n + (r.type === 'skip' ? r.count : 1), 0);
+  return [...rows.slice(0, maxRows), { type: 'more', count: omitted }];
+}
+
+function summarize(file, oldText, newText, extra = {}) {
+  const ops = lineDiff(oldText, newText);
+  return {
+    file,
+    ...extra,
+    added: ops.filter((o) => o.type === 'add').length,
+    removed: ops.filter((o) => o.type === 'del').length,
+    rows: compact(ops),
+  };
+}
+
+// The file as it is now, or null when it's missing, too big, or not text.
+function readExisting(file) {
+  try {
+    if (fs.statSync(file).size > MAX_FILE_BYTES) return undefined;
+    const text = fs.readFileSync(file, 'utf8');
+    return text.includes('\0') ? undefined : text;
+  } catch {
+    return null;
+  }
+}
+
+// What a permission prompt for this tool would change: an array with one entry per file
+// change, or null for tools that don't edit files (or when it can't be worked out).
+function buildDiffs(tool, input, { cwd = '', read = readExisting } = {}) {
+  try {
+    if (!input || typeof input !== 'object') return null;
+    const file = input.file_path;
+    if (tool === 'Edit') return [summarize(file, input.old_string, input.new_string)];
+    if (tool === 'MultiEdit' && Array.isArray(input.edits)) return input.edits.map((e) => summarize(file, e.old_string, e.new_string));
+    if (tool === 'Write' && typeof file === 'string') {
+      const existing = read(path.resolve(cwd || '.', file));
+      if (existing === undefined) return null; // there, but we can't show it
+      return [summarize(file, existing ?? '', input.content, { isNew: existing === null })];
+    }
+  } catch {}
+  return null;
+}
+
+module.exports = { lineDiff, compact, buildDiffs, CONTEXT, MAX_ROWS };

package/lib/doctor.js

@@ -0,0 +1,151 @@
+'use strict';
+// `agenter doctor`: checks the things that silently stop Agenter from working.
+// Every check reads what it needs from ctx, so tests can point it at a temp home folder.
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const http = require('node:http');
+const EVENTS = require('./hook-events');
+
+const ok = (name, detail) => ({ name, status: 'ok', detail });
+const warn = (name, detail, fix) => ({ name, status: 'warn', detail, fix });
+const fail = (name, detail, fix) => ({ name, status: 'fail', detail, fix });
+
+const readJson = (file) => {
+  try {
+    return { value: JSON.parse(fs.readFileSync(file, 'utf8')) };
+  } catch (error) {
+    return { error: error.code === 'ENOENT' ? 'missing' : error.message };
+  }
+};
+
+// Is there an executable called `name` (with the usual Windows extensions) on PATH?
+function onPath(name, env, platform) {
+  const exts = platform === 'win32' ? ['.exe', '.cmd', '.bat', ''] : [''];
+  for (const dir of (env.PATH || env.Path || '').split(path.delimiter)) {
+    for (const ext of exts) if (dir && fs.existsSync(path.join(dir, name + ext))) return true;
+  }
+  return false;
+}
+
+function checkNode(ctx) {
+  const major = Number(String(ctx.nodeVersion).replace(/^v/, '').split('.')[0]);
+  return major >= 18 ? ok('Node.js', `v${String(ctx.nodeVersion).replace(/^v/, '')}`) : fail('Node.js', `${ctx.nodeVersion} is too old (Agenter needs 18+)`, 'Install a current Node.js LTS.');
+}
+
+function checkHooks(ctx) {
+  const name = 'Claude hooks';
+  const file = path.join(ctx.home, '.claude', 'settings.json');
+  const { value, error } = readJson(file);
+  if (error === 'missing') return fail(name, `${file} doesn't exist yet`, 'Run: agenter install');
+  if (error) return fail(name, `${file} isn't valid JSON (${error})`, 'Fix the file, then run: agenter install');
+
+  // Hooks of ours, by event, with the script path each one runs.
+  const ours = {};
+  const scripts = new Set();
+  for (const [event, groups] of Object.entries(value.hooks || {})) {
+    for (const h of (Array.isArray(groups) ? groups : []).flatMap((g) => g?.hooks || [])) {
+      const script = typeof h?.command === 'string' && h.command.match(/"([^"]*[\\/]hook\.js)"/)?.[1];
+      if (!script || !(script.replace(/\\/g, '/') === ctx.hookScript || /agenter/i.test(script))) continue;
+      (ours[event] ||= []).push(script);
+      scripts.add(script);
+    }
+  }
+  if (!scripts.size) return fail(name, "Agenter's hooks aren't in ~/.claude/settings.json, so no sessions will show up", 'Run: agenter install');
+
+  const stale = [...scripts].filter((s) => !fs.existsSync(s));
+  if (stale.length) return fail(name, `a hook points at a file that no longer exists: ${stale[0]}`, 'Run: agenter install (it replaces the old hooks)');
+  const elsewhere = [...scripts].filter((s) => s.replace(/\\/g, '/') !== ctx.hookScript);
+  if (elsewhere.length) return warn(name, `hooks point at another copy of Agenter: ${elsewhere[0]}`, 'Run: agenter install to point them at this one');
+  const missing = Object.keys(EVENTS).filter((e) => !ours[e]);
+  if (missing.length) return warn(name, `no hook for: ${missing.join(', ')}`, 'Run: agenter install');
+  if (!onPath('node', ctx.env, ctx.platform)) return fail(name, 'the hooks run `node`, but node isn\'t on your PATH', 'Add Node.js to PATH, then reload VS Code.');
+  return ok(name, `${Object.keys(EVENTS).length} events installed`);
+}
+
+function checkClaude(ctx) {
+  const bin = ctx.findClaude();
+  return bin
+    ? ok('Claude Code', bin)
+    : warn('Claude Code', "couldn't find it, so \"Drive from Agenter\" and New session won't work (watching and approving still do)", 'Install the Claude Code VS Code extension, or set AGENTER_CLAUDE to the path of claude.exe.');
+}
+
+function checkLogin(ctx) {
+  const name = 'Plan usage login';
+  if (ctx.env.AGENTER_USAGE === '0') return ok(name, 'turned off (AGENTER_USAGE=0)');
+  const { value, error } = readJson(path.join(ctx.home, '.claude', '.credentials.json'));
+  if (error === 'missing') return warn(name, 'no Claude subscription login found, so the usage bars stay empty', 'Sign in with Claude Code using a Claude subscription.');
+  if (error) return warn(name, `couldn't read the saved login (${error})`);
+  const oauth = value.claudeAiOauth;
+  if (!oauth?.accessToken) return warn(name, 'saved login has no subscription token (API-key logins have no plan usage)');
+  if (oauth.expiresAt && oauth.expiresAt < ctx.now) return warn(name, 'saved login has expired; it renews the next time Claude runs');
+  return ok(name, oauth.subscriptionType ? `${oauth.subscriptionType} plan` : 'signed in');
+}
+
+function checkSettings(ctx) {
+  const name = 'Agenter settings';
+  const file = path.join(ctx.home, '.agenter', 'settings.json');
+  const { error } = readJson(file);
+  if (error === 'missing') return ok(name, 'none saved yet (defaults)');
+  return error ? warn(name, `${file} isn't valid JSON, so your settings are ignored (${error})`, 'Fix or delete the file.') : ok(name, file);
+}
+
+async function checkServer(ctx) {
+  const name = `Server (port ${ctx.port})`;
+  const state = await ctx.probeServer(ctx.port);
+  if (state === 'agenter') return ok(name, 'running');
+  if (state === 'other') return fail(name, `something else is using port ${ctx.port}`, 'Close it, or set AGENTER_PORT to another port (for both Agenter and your terminal).');
+  return ok(name, 'not running (it starts itself on the first Claude event, or run: agenter)');
+}
+
+function checkCodex(ctx) {
+  const bin = ctx.findCodex();
+  return bin ? ok('Codex', bin) : ok('Codex', 'not found (only needed to steer Codex sessions)');
+}
+
+// Asks whatever is listening on the port whether it's Agenter.
+function probeServer(port) {
+  return new Promise((resolve) => {
+    const req = http.get({ host: '127.0.0.1', port, path: '/', timeout: 1500 }, (res) => {
+      let body = '';
+      res.setEncoding('utf8');
+      res.on('data', (c) => body.length < 4096 && (body += c));
+      res.on('end', () => resolve(/agenter/i.test(body) ? 'agenter' : 'other'));
+    });
+    req.on('timeout', () => (req.destroy(), resolve('other')));
+    req.on('error', (e) => resolve(e.code === 'ECONNREFUSED' ? 'none' : 'other'));
+  });
+}
+
+async function runChecks(overrides = {}) {
+  const ctx = {
+    home: os.homedir(),
+    env: process.env,
+    platform: process.platform,
+    nodeVersion: process.version,
+    now: Date.now(),
+    port: Number(process.env.AGENTER_PORT) || 4317,
+    hookScript: path.join(__dirname, '..', 'hook.js').replace(/\\/g, '/'),
+    findClaude: () => null,
+    findCodex: () => null,
+    probeServer,
+    ...overrides,
+  };
+  return [checkNode(ctx), checkHooks(ctx), await checkServer(ctx), checkClaude(ctx), checkLogin(ctx), checkSettings(ctx), checkCodex(ctx)];
+}
+
+const MARK = { ok: '✓', warn: '!', fail: '✗' };
+
+function format(results) {
+  const lines = [];
+  for (const r of results) {
+    lines.push(`${MARK[r.status]} ${r.name}: ${r.detail}`);
+    if (r.fix && r.status !== 'ok') lines.push(`    → ${r.fix}`);
+  }
+  const bad = results.filter((r) => r.status === 'fail').length;
+  const odd = results.filter((r) => r.status === 'warn').length;
+  lines.push('', bad ? `${bad} problem${bad === 1 ? '' : 's'} found.` : odd ? 'Working, with some things to look at.' : 'All good.');
+  return lines.join('\n');
+}
+
+module.exports = { runChecks, format, checkHooks, checkLogin, checkSettings, checkServer, checkNode, onPath, probeServer };

package/lib/hook-events.js

@@ -0,0 +1,14 @@
+'use strict';
+// The Claude Code hook events Agenter installs, shared by install.js and `agenter doctor`.
+// timeout is in seconds. Events that can wait for you get an hour.
+module.exports = {
+  SessionStart: { timeout: 10 },
+  SessionEnd: { timeout: 10 },
+  UserPromptSubmit: { timeout: 10 },
+  PreToolUse: { matcher: '*', timeout: 3600 },
+  PostToolUse: { matcher: '*', timeout: 10 },
+  PermissionRequest: { matcher: '*', timeout: 3600 },
+  Notification: { timeout: 10 },
+  Stop: { timeout: 3600 },
+  SubagentStop: { timeout: 10 },
+};

package/lib/limits.js

@@ -0,0 +1,25 @@
+'use strict';
+// Turning plan-usage responses (Anthropic and Codex) into the limits the dashboard shows.
+
+const LIMIT_LABELS = { session: '5-hour session', weekly_all: 'Weekly · all models', weekly_opus: 'Weekly · Opus', weekly_sonnet: 'Weekly · Sonnet' };
+
+function normalizeLimits(j) {
+  if (Array.isArray(j.limits) && j.limits.length) {
+    return j.limits
+      .filter((l) => typeof l.percent === 'number')
+      .map((l) => ({ kind: l.kind, label: LIMIT_LABELS[l.kind] || String(l.kind).replace(/_/g, ' '), percent: l.percent, severity: l.severity || null, resetsAt: l.resets_at || null }));
+  }
+  // Older response shape.
+  const pick = (key, kind) => j[key] && typeof j[key].utilization === 'number' && { kind, label: LIMIT_LABELS[kind], percent: j[key].utilization, severity: null, resetsAt: j[key].resets_at || null };
+  return [pick('five_hour', 'session'), pick('seven_day', 'weekly_all'), pick('seven_day_opus', 'weekly_opus'), pick('seven_day_sonnet', 'weekly_sonnet')].filter(Boolean);
+}
+
+function codexWindowLabel(minutes) {
+  if (minutes === 300) return '5-hour session';
+  if (minutes === 10080) return 'Weekly';
+  if (minutes % 1440 === 0) return `${minutes / 1440}-day`;
+  if (minutes % 60 === 0) return `${minutes / 60}-hour`;
+  return `${minutes}-minute`;
+}
+
+module.exports = { LIMIT_LABELS, normalizeLimits, codexWindowLabel };

package/lib/transcript.js

@@ -0,0 +1,238 @@
+'use strict';
+// Reading Claude Code transcripts and Codex rollouts: pure parsing plus the incremental file reader.
+const fs = require('node:fs');
+const crypto = require('node:crypto');
+
+const truncate = (s, n) => {
+  s = String(s ?? '');
+  return s.length > n ? s.slice(0, n) + `\n… (${s.length - n} more chars)` : s;
+};
+
+function describeTool(name, input = {}) {
+  if (!input || typeof input !== 'object') return '';
+  if (input.command) return input.command;
+  if (name === 'AskUserQuestion' && Array.isArray(input.questions)) return input.questions.map((q) => q.question).join(' / ');
+  if (input.file_path) return input.file_path;
+  if (input.notebook_path) return input.notebook_path;
+  if (input.pattern) return input.pattern + (input.path ? `  in ${input.path}` : '');
+  if (input.url) return input.url;
+  if (input.query) return input.query;
+  if (input.description) return input.description;
+  if (input.prompt) return input.prompt;
+  return JSON.stringify(input);
+}
+
+function readTail(file, maxBytes) {
+  const fd = fs.openSync(file, 'r');
+  try {
+    const size = fs.fstatSync(fd).size;
+    const start = Math.max(0, size - maxBytes);
+    const buf = Buffer.alloc(size - start);
+    fs.readSync(fd, buf, 0, buf.length, start);
+    let text = buf.toString('utf8');
+    if (start > 0) text = text.slice(text.indexOf('\n') + 1); // drop the partial first line
+    return text;
+  } finally {
+    fs.closeSync(fd);
+  }
+}
+
+const resultText = (content) =>
+  typeof content === 'string'
+    ? content
+    : Array.isArray(content)
+      ? content.map((c) => (c.type === 'text' ? c.text : `[${c.type}]`)).join('\n')
+      : '';
+
+const isNoise = (text) => /^\s*<(system-reminder|ide_|command-|local-command)/.test(text);
+
+// Appends the messages in these transcript lines to out (metadata and noise skipped).
+// Reads both Claude Code transcripts and Codex rollouts.
+function parseLines(text, out) {
+  for (const line of text.split('\n')) {
+    if (!line.trim()) continue;
+    let e;
+    try {
+      e = JSON.parse(line);
+    } catch {
+      continue;
+    }
+    if (e.type === 'response_item') {
+      parseCodexItem(e, out);
+      continue;
+    }
+    if ((e.type !== 'user' && e.type !== 'assistant') || e.isMeta || !e.message) continue;
+    const ts = e.timestamp;
+    const content = e.message.content;
+    if (typeof content === 'string') {
+      if (!isNoise(content)) out.push({ role: e.type, kind: 'text', text: content, ts });
+      continue;
+    }
+    if (!Array.isArray(content)) continue;
+    for (const b of content) {
+      if (b.type === 'text' && b.text?.trim() && !isNoise(b.text)) out.push({ role: e.type, kind: 'text', text: b.text, ts });
+      else if (b.type === 'tool_use') out.push({ role: 'assistant', kind: 'tool', id: b.id, name: b.name, text: describeTool(b.name, b.input), ts });
+      else if (b.type === 'tool_result') out.push({ role: 'tool', kind: 'result', toolUseId: b.tool_use_id, text: resultText(b.content), isError: !!b.is_error, ts });
+    }
+  }
+  return out;
+}
+
+// Codex's exec tool takes a small script; the shell command inside it is what's worth showing.
+function describeCodexCall(name, input) {
+  const raw = String(input ?? '');
+  if (name === 'wait') return 'Waiting for the running command';
+  const m = raw.match(/\bcmd\s*:\s*(["'`])((?:\\.|(?!\1)[^\\])*)\1/);
+  if (m) return m[2].replace(/\\(.)/g, (_, c) => ({ n: '\n', t: '\t' })[c] ?? c);
+  // Other built-in tools called from the script: name them, plus the search query if any.
+  const call = raw.match(/\btools\.(\w+)\(/)?.[1];
+  if (call === 'write_stdin') return 'Sending input to the running command';
+  if (call) {
+    const q = raw.match(/\bq\s*:\s*(["'`])((?:\\.|(?!\1)[^\\])*)\1/)?.[2];
+    return call.replace(/__/g, ' ') + (q ? `: ${q}` : '');
+  }
+  try {
+    const args = JSON.parse(raw);
+    if (args && typeof args === 'object') return describeTool(name, args);
+  } catch {}
+  return raw.split('\n')[0];
+}
+
+const codexOutput = (o) => (typeof o === 'string' ? o : Array.isArray(o) ? o.map((c) => c.text ?? `[${c.type}]`).join('\n') : '');
+
+function parseCodexItem(e, out) {
+  const p = e.payload || {};
+  const ts = e.timestamp;
+  if (p.type === 'message' && (p.role === 'user' || p.role === 'assistant')) {
+    // Only what you typed: Codex also sends context (environment, open pages) as user messages.
+    const kinds = p.internal_chat_message_metadata_passthrough?.content_item_kinds;
+    (p.content || []).forEach((c, i) => {
+      const text = c.text?.trim();
+      if (!text) return;
+      if (p.role === 'user' && (kinds ? kinds[i] !== 'user.text' : text.startsWith('<'))) return;
+      // The VS Code extension wraps what you typed in IDE context (open tabs etc.).
+      const typed = p.role === 'user' ? c.text.match(/^#+ My request:\s*\n([\s\S]*)$/m)?.[1] : null;
+      out.push({ role: p.role, kind: 'text', text: typed?.trim() || c.text, ts });
+    });
+  } else if (p.type === 'function_call' || p.type === 'custom_tool_call') {
+    out.push({ role: 'assistant', kind: 'tool', id: p.call_id, name: p.name, text: describeCodexCall(p.name, p.arguments ?? p.input), ts });
+  } else if (p.type === 'function_call_output' || p.type === 'custom_tool_call_output') {
+    out.push({ role: 'tool', kind: 'result', toolUseId: p.call_id, text: codexOutput(p.output), isError: false, ts });
+  }
+}
+
+const clipMessage = (m) => ({ ...m, text: truncate(m.text, m.kind === 'result' ? 4000 : 20000) });
+
+function parseTranscript(file, limit = 120) {
+  if (!file || !fs.existsSync(file)) return [];
+  return parseLines(readTail(file, TRANSCRIPT_TAIL), []).slice(-limit).map(clipMessage);
+}
+
+// The conversation open on the dashboard is read incrementally: each request parses
+// only the bytes appended since the last one. Messages get increasing seq numbers so
+// the dashboard can ask for just the new ones; epoch changes if the file is replaced.
+const TRANSCRIPT_TAIL = 2 * 1024 * 1024;
+const TRANSCRIPT_KEEP = 400;
+const TRANSCRIPT_FILES = 8;
+const transcriptCache = new Map(); // file -> { epoch, offset, rest, dropFirstLine, seq, messages }
+
+function readTranscript(file) {
+  let size;
+  try {
+    size = fs.statSync(file).size;
+  } catch {
+    return null;
+  }
+  let c = transcriptCache.get(file);
+  if (!c || size < c.offset) {
+    const offset = Math.max(0, size - TRANSCRIPT_TAIL);
+    c = { epoch: crypto.randomUUID(), offset, rest: Buffer.alloc(0), dropFirstLine: offset > 0, seq: 0, messages: [] };
+  }
+  transcriptCache.delete(file); // most recently used goes last
+  transcriptCache.set(file, c);
+  if (transcriptCache.size > TRANSCRIPT_FILES) transcriptCache.delete(transcriptCache.keys().next().value);
+  if (size === c.offset) return c;
+
+  const fd = fs.openSync(file, 'r');
+  let buf;
+  try {
+    buf = Buffer.alloc(size - c.offset);
+    fs.readSync(fd, buf, 0, buf.length, c.offset);
+  } finally {
+    fs.closeSync(fd);
+  }
+  c.offset = size;
+  buf = Buffer.concat([c.rest, buf]);
+  let start = 0;
+  if (c.dropFirstLine) {
+    start = buf.indexOf(10) + 1; // we started mid-file: skip the partial first line
+    if (start) c.dropFirstLine = false;
+  }
+  // Only complete lines. Splitting on the newline byte never cuts a UTF-8 character.
+  const end = Math.max(start, buf.lastIndexOf(10) + 1);
+  c.rest = Buffer.from(buf.subarray(end));
+  for (const m of parseLines(buf.toString('utf8', start, end), [])) c.messages.push({ ...clipMessage(m), seq: ++c.seq });
+  if (c.messages.length > TRANSCRIPT_KEEP) c.messages.splice(0, c.messages.length - TRANSCRIPT_KEEP);
+  return c;
+}
+
+function lastAssistantText(file) {
+  const msgs = parseTranscript(file, 400);
+  for (let i = msgs.length - 1; i >= 0; i--) if (msgs[i].role === 'assistant' && msgs[i].kind === 'text') return msgs[i].text;
+  return '';
+}
+
+function readHead(file, maxBytes) {
+  const fd = fs.openSync(file, 'r');
+  try {
+    const buf = Buffer.alloc(Math.min(maxBytes, fs.fstatSync(fd).size));
+    fs.readSync(fd, buf, 0, buf.length, 0);
+    return buf.toString('utf8');
+  } finally {
+    fs.closeSync(fd);
+  }
+}
+
+const firstText = (content) =>
+  typeof content === 'string' ? content : Array.isArray(content) ? content.find((b) => b.type === 'text' && !isNoise(b.text || ''))?.text || '' : '';
+
+// cwd and a title (Claude's summary, else the first prompt) from the start of a transcript.
+function transcriptInfo(file) {
+  let cwd = '';
+  let prompt = '';
+  let summary = '';
+  for (const line of readHead(file, 256 * 1024).split('\n')) {
+    let e;
+    try {
+      e = JSON.parse(line);
+    } catch {
+      continue;
+    }
+    if (!cwd && e.cwd) cwd = e.cwd;
+    if (e.type === 'summary' && e.summary && !summary) summary = e.summary;
+    if (!prompt && e.type === 'user' && !e.isMeta) {
+      const t = firstText(e.message?.content);
+      if (t && !isNoise(t)) prompt = t;
+    }
+    if (cwd && prompt) break;
+  }
+  return { cwd, title: (summary || prompt).split('\n')[0].slice(0, 140) };
+}
+
+module.exports = {
+  truncate,
+  describeTool,
+  describeCodexCall,
+  readTail,
+  readHead,
+  parseLines,
+  parseCodexItem,
+  parseTranscript,
+  readTranscript,
+  lastAssistantText,
+  transcriptInfo,
+  isNoise,
+  TRANSCRIPT_TAIL,
+  TRANSCRIPT_KEEP,
+  TRANSCRIPT_FILES,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agenter-app",
-  "version": "1.0.2",
+  "version": "1.0.3",
   "description": "One local dashboard to watch, approve and steer every Claude Code and Codex session on your machine.",
   "keywords": [
     "claude",
@@ -38,6 +38,7 @@
   "scripts": {
     "start": "node server.js",
     "open": "node open.js",
+    "test": "node --test",
     "shortcuts": "powershell -NoProfile -ExecutionPolicy Bypass -File scripts/install-shortcuts.ps1",
     "shortcuts:startup": "powershell -NoProfile -ExecutionPolicy Bypass -File scripts/install-shortcuts.ps1 -Startup",
     "install-hooks": "node install.js",

package/public/app.js

@@ -994,8 +994,23 @@ function keyAct(action) {
   act(card, action);
 }
 
-function renderToolBody(tool, input = {}) {
+// One file's changes, as built by the server (lib/diff.js): unchanged lines around each change.
+function renderDiff(d) {
+  const sign = { ctx: ' ', del: '−', add: '+' };
+  const rows = d.rows
+    .map((r) => {
+      if (r.type === 'skip') return `<div class="skip">⋯ ${r.count} unchanged line${r.count === 1 ? '' : 's'}</div>`;
+      if (r.type === 'more') return `<div class="skip">⋯ ${r.count} more lines not shown</div>`;
+      return `<div class="${r.type}">${sign[r.type]} ${esc(r.text)}</div>`;
+    })
+    .join('');
+  const stats = `<span class="add-n">+${d.added}</span> <span class="del-n">−${d.removed}</span>`;
+  return `<div class="diff-head"><span class="path mono">${esc(d.file)}</span>${d.isNew ? '<span class="pill plain">New file</span>' : ''}<span class="diff-stats">${stats}</span></div><div class="diff mono">${rows || '<div class="skip">No changes</div>'}</div>`;
+}
+
+function renderToolBody(tool, input = {}, diffs = null) {
   input = input || {};
+  if (diffs?.length) return diffs.map(renderDiff).join('');
   if (['Bash', 'PowerShell'].includes(tool) || typeof input.command === 'string') {
     return `${input.description ? `<div class="desc">${esc(input.description)}</div>` : ''}<pre class="cmd shell">${esc(input.command)}</pre>`;
   }
@@ -1029,7 +1044,7 @@ function renderCard(p, showSession) {
     const risky = isDestructive(p);
     return `<div class="card kind-permission ${risky ? 'risky' : ''}" data-id="${p.id}">${sessionBar}<div class="card-body">
       ${head(toolIcon(p.tool), `Allow <span class="mono">${esc(toolName(p.tool))}</span>?`, 'Claude is asking for permission')}
-      <div class="tool-body">${renderToolBody(p.tool, p.input)}</div>
+      <div class="tool-body">${renderToolBody(p.tool, p.input, p.diffs)}</div>
       ${risky ? `<div class="risk-note">${icon('shield')}<span>This looks destructive, so the <kbd>A</kbd> shortcut is off. Read it, then click Allow if it's fine.</span></div>` : ''}
       <div class="actions">
         <button class="btn primary" data-act="allow">${icon('check')}Allow${risky ? '' : ' <kbd>A</kbd>'}</button>

package/public/style.css

@@ -457,6 +457,12 @@ dialog.new-dialog { max-width: 520px; }
 .diff div { padding: 0 10px; white-space: pre-wrap; word-break: break-word; }
 .diff .del { background: var(--del-bg); }
 .diff .add { background: var(--add-bg); }
+.diff .skip { color: var(--muted); font-size: 11.5px; padding-top: 2px; padding-bottom: 2px; background: var(--panel-2); user-select: none; }
+.diff-head { display: flex; align-items: center; gap: 8px; margin-bottom: 6px; }
+.diff-head .path { margin-bottom: 0; min-width: 0; }
+.diff-stats { margin-left: auto; flex: none; font-size: 12px; font-weight: 600; }
+.diff-stats .add-n { color: var(--ok, #2e7d32); }
+.diff-stats .del-n { color: var(--danger); }
 
 .actions { display: flex; gap: 8px; flex-wrap: wrap; align-items: center; }
 .actions .grow { flex: 1; min-width: 180px; }

package/server.js

@@ -9,6 +9,9 @@ const os = require('node:os');
 const crypto = require('node:crypto');
 const { spawn, execFile } = require('node:child_process');
 const openDashboard = require('./lib/open-dashboard');
+const { truncate, describeTool, readTail, readHead, parseCodexItem, readTranscript, lastAssistantText, transcriptInfo } = require('./lib/transcript');
+const { normalizeLimits, codexWindowLabel } = require('./lib/limits');
+const { buildDiffs } = require('./lib/diff');
 
 const PORT = Number(process.env.AGENTER_PORT) || 4317;
 const HOST = '127.0.0.1';
@@ -49,224 +52,6 @@ const saveSettings = () => {
   fs.writeFileSync(SETTINGS_FILE, JSON.stringify(settings, null, 2));
 };
 
-// ---------- helpers ----------
-
-const truncate = (s, n) => {
-  s = String(s ?? '');
-  return s.length > n ? s.slice(0, n) + `\n… (${s.length - n} more chars)` : s;
-};
-
-function describeTool(name, input = {}) {
-  if (!input || typeof input !== 'object') return '';
-  if (input.command) return input.command;
-  if (name === 'AskUserQuestion' && Array.isArray(input.questions)) return input.questions.map((q) => q.question).join(' / ');
-  if (input.file_path) return input.file_path;
-  if (input.notebook_path) return input.notebook_path;
-  if (input.pattern) return input.pattern + (input.path ? `  in ${input.path}` : '');
-  if (input.url) return input.url;
-  if (input.query) return input.query;
-  if (input.description) return input.description;
-  if (input.prompt) return input.prompt;
-  return JSON.stringify(input);
-}
-
-function readTail(file, maxBytes) {
-  const fd = fs.openSync(file, 'r');
-  try {
-    const size = fs.fstatSync(fd).size;
-    const start = Math.max(0, size - maxBytes);
-    const buf = Buffer.alloc(size - start);
-    fs.readSync(fd, buf, 0, buf.length, start);
-    let text = buf.toString('utf8');
-    if (start > 0) text = text.slice(text.indexOf('\n') + 1); // drop the partial first line
-    return text;
-  } finally {
-    fs.closeSync(fd);
-  }
-}
-
-const resultText = (content) =>
-  typeof content === 'string'
-    ? content
-    : Array.isArray(content)
-      ? content.map((c) => (c.type === 'text' ? c.text : `[${c.type}]`)).join('\n')
-      : '';
-
-const isNoise = (text) => /^\s*<(system-reminder|ide_|command-|local-command)/.test(text);
-
-// Appends the messages in these transcript lines to out (metadata and noise skipped).
-// Reads both Claude Code transcripts and Codex rollouts.
-function parseLines(text, out) {
-  for (const line of text.split('\n')) {
-    if (!line.trim()) continue;
-    let e;
-    try {
-      e = JSON.parse(line);
-    } catch {
-      continue;
-    }
-    if (e.type === 'response_item') {
-      parseCodexItem(e, out);
-      continue;
-    }
-    if ((e.type !== 'user' && e.type !== 'assistant') || e.isMeta || !e.message) continue;
-    const ts = e.timestamp;
-    const content = e.message.content;
-    if (typeof content === 'string') {
-      if (!isNoise(content)) out.push({ role: e.type, kind: 'text', text: content, ts });
-      continue;
-    }
-    if (!Array.isArray(content)) continue;
-    for (const b of content) {
-      if (b.type === 'text' && b.text?.trim() && !isNoise(b.text)) out.push({ role: e.type, kind: 'text', text: b.text, ts });
-      else if (b.type === 'tool_use') out.push({ role: 'assistant', kind: 'tool', id: b.id, name: b.name, text: describeTool(b.name, b.input), ts });
-      else if (b.type === 'tool_result') out.push({ role: 'tool', kind: 'result', toolUseId: b.tool_use_id, text: resultText(b.content), isError: !!b.is_error, ts });
-    }
-  }
-  return out;
-}
-
-// Codex's exec tool takes a small script; the shell command inside it is what's worth showing.
-function describeCodexCall(name, input) {
-  const raw = String(input ?? '');
-  if (name === 'wait') return 'Waiting for the running command';
-  const m = raw.match(/\bcmd\s*:\s*(["'`])((?:\\.|(?!\1)[^\\])*)\1/);
-  if (m) return m[2].replace(/\\(.)/g, (_, c) => ({ n: '\n', t: '\t' })[c] ?? c);
-  // Other built-in tools called from the script: name them, plus the search query if any.
-  const call = raw.match(/\btools\.(\w+)\(/)?.[1];
-  if (call === 'write_stdin') return 'Sending input to the running command';
-  if (call) {
-    const q = raw.match(/\bq\s*:\s*(["'`])((?:\\.|(?!\1)[^\\])*)\1/)?.[2];
-    return call.replace(/__/g, ' ') + (q ? `: ${q}` : '');
-  }
-  try {
-    const args = JSON.parse(raw);
-    if (args && typeof args === 'object') return describeTool(name, args);
-  } catch {}
-  return raw.split('\n')[0];
-}
-
-const codexOutput = (o) => (typeof o === 'string' ? o : Array.isArray(o) ? o.map((c) => c.text ?? `[${c.type}]`).join('\n') : '');
-
-function parseCodexItem(e, out) {
-  const p = e.payload || {};
-  const ts = e.timestamp;
-  if (p.type === 'message' && (p.role === 'user' || p.role === 'assistant')) {
-    // Only what you typed: Codex also sends context (environment, open pages) as user messages.
-    const kinds = p.internal_chat_message_metadata_passthrough?.content_item_kinds;
-    (p.content || []).forEach((c, i) => {
-      const text = c.text?.trim();
-      if (!text) return;
-      if (p.role === 'user' && (kinds ? kinds[i] !== 'user.text' : text.startsWith('<'))) return;
-      // The VS Code extension wraps what you typed in IDE context (open tabs etc.).
-      const typed = p.role === 'user' ? c.text.match(/^#+ My request:\s*\n([\s\S]*)$/m)?.[1] : null;
-      out.push({ role: p.role, kind: 'text', text: typed?.trim() || c.text, ts });
-    });
-  } else if (p.type === 'function_call' || p.type === 'custom_tool_call') {
-    out.push({ role: 'assistant', kind: 'tool', id: p.call_id, name: p.name, text: describeCodexCall(p.name, p.arguments ?? p.input), ts });
-  } else if (p.type === 'function_call_output' || p.type === 'custom_tool_call_output') {
-    out.push({ role: 'tool', kind: 'result', toolUseId: p.call_id, text: codexOutput(p.output), isError: false, ts });
-  }
-}
-
-const clipMessage = (m) => ({ ...m, text: truncate(m.text, m.kind === 'result' ? 4000 : 20000) });
-
-function parseTranscript(file, limit = 120) {
-  if (!file || !fs.existsSync(file)) return [];
-  return parseLines(readTail(file, TRANSCRIPT_TAIL), []).slice(-limit).map(clipMessage);
-}
-
-// The conversation open on the dashboard is read incrementally: each request parses
-// only the bytes appended since the last one. Messages get increasing seq numbers so
-// the dashboard can ask for just the new ones; epoch changes if the file is replaced.
-const TRANSCRIPT_TAIL = 2 * 1024 * 1024;
-const TRANSCRIPT_KEEP = 400;
-const TRANSCRIPT_FILES = 8;
-const transcriptCache = new Map(); // file -> { epoch, offset, rest, dropFirstLine, seq, messages }
-
-function readTranscript(file) {
-  let size;
-  try {
-    size = fs.statSync(file).size;
-  } catch {
-    return null;
-  }
-  let c = transcriptCache.get(file);
-  if (!c || size < c.offset) {
-    const offset = Math.max(0, size - TRANSCRIPT_TAIL);
-    c = { epoch: crypto.randomUUID(), offset, rest: Buffer.alloc(0), dropFirstLine: offset > 0, seq: 0, messages: [] };
-  }
-  transcriptCache.delete(file); // most recently used goes last
-  transcriptCache.set(file, c);
-  if (transcriptCache.size > TRANSCRIPT_FILES) transcriptCache.delete(transcriptCache.keys().next().value);
-  if (size === c.offset) return c;
-
-  const fd = fs.openSync(file, 'r');
-  let buf;
-  try {
-    buf = Buffer.alloc(size - c.offset);
-    fs.readSync(fd, buf, 0, buf.length, c.offset);
-  } finally {
-    fs.closeSync(fd);
-  }
-  c.offset = size;
-  buf = Buffer.concat([c.rest, buf]);
-  let start = 0;
-  if (c.dropFirstLine) {
-    start = buf.indexOf(10) + 1; // we started mid-file: skip the partial first line
-    if (start) c.dropFirstLine = false;
-  }
-  // Only complete lines. Splitting on the newline byte never cuts a UTF-8 character.
-  const end = Math.max(start, buf.lastIndexOf(10) + 1);
-  c.rest = Buffer.from(buf.subarray(end));
-  for (const m of parseLines(buf.toString('utf8', start, end), [])) c.messages.push({ ...clipMessage(m), seq: ++c.seq });
-  if (c.messages.length > TRANSCRIPT_KEEP) c.messages.splice(0, c.messages.length - TRANSCRIPT_KEEP);
-  return c;
-}
-
-function lastAssistantText(file) {
-  const msgs = parseTranscript(file, 400);
-  for (let i = msgs.length - 1; i >= 0; i--) if (msgs[i].role === 'assistant' && msgs[i].kind === 'text') return msgs[i].text;
-  return '';
-}
-
-function readHead(file, maxBytes) {
-  const fd = fs.openSync(file, 'r');
-  try {
-    const buf = Buffer.alloc(Math.min(maxBytes, fs.fstatSync(fd).size));
-    fs.readSync(fd, buf, 0, buf.length, 0);
-    return buf.toString('utf8');
-  } finally {
-    fs.closeSync(fd);
-  }
-}
-
-const firstText = (content) =>
-  typeof content === 'string' ? content : Array.isArray(content) ? content.find((b) => b.type === 'text' && !isNoise(b.text || ''))?.text || '' : '';
-
-// cwd and a title (Claude's summary, else the first prompt) from the start of a transcript.
-function transcriptInfo(file) {
-  let cwd = '';
-  let prompt = '';
-  let summary = '';
-  for (const line of readHead(file, 256 * 1024).split('\n')) {
-    let e;
-    try {
-      e = JSON.parse(line);
-    } catch {
-      continue;
-    }
-    if (!cwd && e.cwd) cwd = e.cwd;
-    if (e.type === 'summary' && e.summary && !summary) summary = e.summary;
-    if (!prompt && e.type === 'user' && !e.isMeta) {
-      const t = firstText(e.message?.content);
-      if (t && !isNoise(t)) prompt = t;
-    }
-    if (cwd && prompt) break;
-  }
-  return { cwd, title: (summary || prompt).split('\n')[0].slice(0, 140) };
-}
-
 // ---------- sessions ----------
 
 const newSession = (id) => ({ id, agent: 'claude', cwd: '', project: '', title: '', transcriptPath: '', status: 'idle', hold: null, startedAt: Date.now(), lastEventAt: 0, lastAction: '', permissionMode: '', activity: [], queue: [] });
@@ -392,19 +177,6 @@ function startDiscovery() {
 // ---------- plan usage ----------
 
 let usage = null; // { fetchedAt, plan, limits: [...], error }
-const LIMIT_LABELS = { session: '5-hour session', weekly_all: 'Weekly · all models', weekly_opus: 'Weekly · Opus', weekly_sonnet: 'Weekly · Sonnet' };
-
-function normalizeLimits(j) {
-  if (Array.isArray(j.limits) && j.limits.length) {
-    return j.limits
-      .filter((l) => typeof l.percent === 'number')
-      .map((l) => ({ kind: l.kind, label: LIMIT_LABELS[l.kind] || String(l.kind).replace(/_/g, ' '), percent: l.percent, severity: l.severity || null, resetsAt: l.resets_at || null }));
-  }
-  // Older response shape.
-  const pick = (key, kind) => j[key] && typeof j[key].utilization === 'number' && { kind, label: LIMIT_LABELS[kind], percent: j[key].utilization, severity: null, resetsAt: j[key].resets_at || null };
-  return [pick('five_hour', 'session'), pick('seven_day', 'weekly_all'), pick('seven_day_opus', 'weekly_opus'), pick('seven_day_sonnet', 'weekly_sonnet')].filter(Boolean);
-}
-
 // The usage endpoint is rate-limited per account (Claude Code's /usage calls it too).
 // After a 429 we wait before asking again, longer each time, instead of keeping the
 // limit tripped by retrying every couple of minutes.
@@ -666,14 +438,6 @@ function startCodexDiscovery() {
 // Codex records your plan limits with every turn (the same numbers its /status shows).
 let codexUsage = null; // { updatedAt, plan, limits, credits }
 
-function codexWindowLabel(minutes) {
-  if (minutes === 300) return '5-hour session';
-  if (minutes === 10080) return 'Weekly';
-  if (minutes % 1440 === 0) return `${minutes / 1440}-day`;
-  if (minutes % 60 === 0) return `${minutes / 60}-hour`;
-  return `${minutes}-minute`;
-}
-
 function noteCodexLimits(rl, at) {
   if (codexUsage && at <= codexUsage.updatedAt) return;
   const limits = [];
@@ -1146,7 +910,8 @@ function handleHook(p, res) {
     case 'PermissionRequest':
       if (watching && p.tool_name !== 'AskUserQuestion') {
         const canAlways = Array.isArray(p.permission_suggestions) && p.permission_suggestions.length > 0;
-        return hold(s, 'permission', { tool: p.tool_name, input: p.tool_input, canAlways }, p, res);
+        const diffs = buildDiffs(p.tool_name, p.tool_input, { cwd: p.cwd || s.cwd });
+        return hold(s, 'permission', { tool: p.tool_name, input: p.tool_input, canAlways, ...(diffs && { diffs }) }, p, res);
       }
       s.status = 'vscode';
       break;
@@ -1420,17 +1185,27 @@ const server = http.createServer(async (req, res) => {
 });
 
 server.requestTimeout = 0; // hooks can legitimately wait a long time for you
-server.on('error', (err) => {
-  if (err.code === 'EADDRINUSE') console.error(`Port ${PORT} is busy. Is Agenter already running? (Set AGENTER_PORT to use another port.)`);
-  else console.error(err);
-  process.exit(1);
-});
-server.listen(PORT, HOST, () => {
-  const url = `http://localhost:${PORT}`;
-  console.log(`Agenter dashboard: ${url}`);
-  startDiscovery();
-  startCodexDiscovery();
-  fetchUsage();
-  setInterval(fetchUsage, USAGE_INTERVAL_MS);
-  if (!process.argv.includes('--no-open')) openDashboard(url);
-});
+// Only listen when run directly; the tests load this file to drive the hook and steering logic.
+if (require.main === module) {
+  server.on('error', (err) => {
+    if (err.code === 'EADDRINUSE') console.error(`Port ${PORT} is busy. Is Agenter already running? (Set AGENTER_PORT to use another port.)`);
+    else console.error(err);
+    process.exit(1);
+  });
+  server.listen(PORT, HOST, () => {
+    const url = `http://localhost:${PORT}`;
+    console.log(`Agenter dashboard: ${url}`);
+    startDiscovery();
+    startCodexDiscovery();
+    fetchUsage();
+    setInterval(fetchUsage, USAGE_INTERVAL_MS);
+    if (!process.argv.includes('--no-open')) openDashboard(url);
+  });
+}
+
+module.exports = {
+  sessions, pending, clients, runners, dismissed,
+  get settings() { return settings; },
+  handleHook, hold, respond, steer, takeQueue, touchSession, snapshot, driveOf, effectiveHold,
+  findClaude, findCodex,
+};