agentglow 0.2.0 → 0.2.2

package/README.md

@@ -8,6 +8,23 @@ Python server, so it works with LangGraph, deepagents, LangChain and anything el
 
 ![neural theme](https://raw.githubusercontent.com/Nideesh1/agentglow/main/docs/media/hero.gif)
 
+## Watch Claude Code (CLI)
+
+```bash
+npx agentglow claude
+```
+Starts the AgentGlow server (fetching uv + Python on first run, so only Node 18+ is needed), opens the 3D view
+and runs `claude` with AgentGlow hooks + traces. Your agents and subagents appear live as Claude works.
+
+| Command | What it does |
+|---|---|
+| `npx agentglow claude [--port 8100] [--no-open] [-- <claude args>]` | start/reuse the server, open `/neural`, run Claude Code with AgentGlow attached |
+| `npx agentglow claude --install` / `--uninstall` | add/remove the AgentGlow hooks + env in `~/.claude/settings.json` (backup first) |
+| `npx agentglow serve` / `stop` / `open` `[--port 8100]` | run the server in the foreground / stop a background one / open the view |
+
+`AGENTGLOW_URL` points everything at a remote server, `AGENTGLOW_API_KEY` sends an ingest key. Details:
+[examples/claude-code](https://github.com/Nideesh1/agentglow/tree/main/examples/claude-code#cli).
+
 ## Install
 
 ```bash

package/cli/agentglow.mjs

@@ -0,0 +1,177 @@
+#!/usr/bin/env node
+// agentglow CLI: watch Claude Code in 3D with one command. Needs only Node >= 18 (uv + Python are fetched on demand).
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { spawn } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { probe } from "./lib/net.mjs";
+import { baseUrl, claudeSettings, installSettingsFile, uninstallSettingsFile } from "./lib/settings.mjs";
+import { localBase, readPid, serveForeground, startBackground, stopServer } from "./lib/server.mjs";
+import { which } from "./lib/uv.mjs";
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+const VERSION = (() => {
+  try { return JSON.parse(fs.readFileSync(path.join(here, "..", "package.json"), "utf8")).version; } catch { return ""; }
+})();
+
+const HELP = `agentglow ${VERSION}: live 3D views of agent systems
+
+Usage:
+  npx agentglow claude [--port 8100] [--no-open] [-- <claude args...>]
+      Start (or reuse) the AgentGlow server, open /neural and run Claude Code with AgentGlow hooks + traces.
+  npx agentglow claude --install [--port 8100]
+      Add the AgentGlow hooks + traces env to ~/.claude/settings.json (backup first). Plain \`claude\` then reports.
+  npx agentglow claude --uninstall
+      Remove exactly what --install added.
+  npx agentglow serve [--port 8100]     Run the server in the foreground.
+  npx agentglow stop  [--port 8100]     Stop a server this CLI started in the background.
+  npx agentglow open  [--port 8100]     Open the 3D view in your browser.
+
+Environment:
+  AGENTGLOW_URL       use this (remote) server instead of starting one, e.g. https://glow.example.com
+  AGENTGLOW_API_KEY   ingest key, sent as x-api-key by the hooks and the OTel traces
+  AGENTGLOW_CACHE_DIR where uv, the pidfile and server logs live
+`;
+
+function fail(msg, code = 1) {
+  console.error(`agentglow: ${msg}`);
+  process.exit(code);
+}
+
+function parseArgs(argv) {
+  const o = { cmd: argv[0], port: Number(process.env.AGENTGLOW_PORT) || 8100, open: true, install: false, uninstall: false, rest: [] };
+  const args = argv.slice(1);
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a === "--") { o.rest.push(...args.slice(i + 1)); break; }
+    else if (a === "--port") o.port = Number(args[++i]);
+    else if (a.startsWith("--port=")) o.port = Number(a.slice(7));
+    else if (a === "--no-open") o.open = false;
+    else if (a === "--install") o.install = true;
+    else if (a === "--uninstall") o.uninstall = true;
+    else if (a === "-h" || a === "--help") o.help = true;
+    else o.rest.push(a); // anything else goes to claude
+  }
+  if (!Number.isInteger(o.port) || o.port < 1 || o.port > 65535) fail("--port must be a number between 1 and 65535");
+  return o;
+}
+
+function openBrowser(url) {
+  const [cmd, args] = process.platform === "darwin" ? ["open", [url]]
+    : process.platform === "win32" ? ["cmd", ["/c", "start", "", url]]
+    : ["xdg-open", [url]];
+  try {
+    const c = spawn(cmd, args, { stdio: "ignore", detached: true, windowsHide: true });
+    c.on("error", () => console.error(`Open ${url} in your browser.`));
+    c.unref();
+  } catch { console.error(`Open ${url} in your browser.`); }
+}
+
+const remoteUrl = () => (process.env.AGENTGLOW_URL || "").replace(/\/+$/, "") || null;
+
+/** Make sure a server answers; returns { base (for hooks + browser), started }. */
+async function ensureServer(port) {
+  const remote = remoteUrl();
+  if (remote) {
+    const st = await probe(remote, 4000);
+    if (st !== "agentglow") console.error(`agentglow: warning: ${remote}/live/health did not answer like AgentGlow; Claude Code will run anyway.`);
+    return { base: remote, started: false };
+  }
+  const st = await probe(localBase(port));
+  if (st === "agentglow") return { base: baseUrl({ port }), started: false };
+  if (st === "other") fail(`port ${port} is in use by something that is not AgentGlow. Pick another one: --port ${port + 1}`);
+  await startBackground({ port, version: VERSION });
+  return { base: baseUrl({ port }), started: true };
+}
+
+async function cmdClaude(o) {
+  if (o.install || o.uninstall) {
+    const file = path.join(os.homedir(), ".claude", "settings.json");
+    if (o.uninstall) {
+      const r = uninstallSettingsFile(file);
+      console.log(r.changed ? `Removed the AgentGlow hooks + env from ${file} (backup: ${r.backup})` : `No AgentGlow entries in ${file}.`);
+      return 0;
+    }
+    const base = remoteUrl() || baseUrl({ port: o.port });
+    const r = installSettingsFile(file, base);
+    if (!r.changed) console.log(`AgentGlow is already installed in ${file} (${base}).`);
+    else console.log(`Installed AgentGlow hooks + traces env into ${file}${r.backup ? ` (backup: ${r.backup})` : ""}.`);
+    if (r.skipped.length) console.log(`Left your own values for: ${r.skipped.join(", ")}`);
+    if (process.env.AGENTGLOW_API_KEY) console.log('For traces with an ingest key also export OTEL_EXPORTER_OTLP_HEADERS="x-api-key=$AGENTGLOW_API_KEY".');
+    console.log(`Every \`claude\` session now reports to ${base}. Start the server with: npx agentglow serve${o.port !== 8100 ? ` --port ${o.port}` : ""}`);
+    console.log("Undo with: npx agentglow claude --uninstall");
+    return 0;
+  }
+
+  const claude = which("claude");
+  if (!claude) fail("`claude` is not on your PATH. Install Claude Code first: npm i -g @anthropic-ai/claude-code");
+
+  const { base, started } = await ensureServer(o.port);
+  const view = `${base}/neural`;
+  console.error(`AgentGlow: ${view}${started ? " (server started in the background)" : ""}`);
+  if (o.open) openBrowser(view);
+
+  const tmp = path.join(os.tmpdir(), `agentglow-claude-${process.pid}.json`);
+  fs.writeFileSync(tmp, JSON.stringify(claudeSettings(base), null, 2));
+  const env = { ...process.env };
+  if (env.AGENTGLOW_API_KEY && !env.OTEL_EXPORTER_OTLP_HEADERS) env.OTEL_EXPORTER_OTLP_HEADERS = `x-api-key=${env.AGENTGLOW_API_KEY}`;
+
+  const code = await new Promise((resolve) => {
+    const win = process.platform === "win32";
+    const args = ["--settings", tmp, ...o.rest];
+    const child = win
+      ? spawn([claude, ...args].map((a) => (/[\s"]/.test(a) ? `"${a.replace(/"/g, '\\"')}"` : a)).join(" "), { stdio: "inherit", env, shell: true })
+      : spawn(claude, args, { stdio: "inherit", env });
+    // Claude Code handles Ctrl-C itself; don't let it kill us before we can clean up
+    const ignore = () => {};
+    process.on("SIGINT", ignore);
+    child.on("error", (e) => { console.error(`agentglow: could not start claude: ${e.message}`); resolve(1); });
+    child.on("exit", (c, sig) => {
+      process.off("SIGINT", ignore);
+      resolve(c ?? (sig === "SIGINT" ? 130 : sig === "SIGTERM" ? 143 : 1));
+    });
+  });
+  try { fs.rmSync(tmp, { force: true }); } catch { /* ignore */ }
+  if (!remoteUrl() && readPid(o.port)) {
+    console.error(`AgentGlow is still running at ${view}. Stop it with: npx agentglow stop${o.port !== 8100 ? ` --port ${o.port}` : ""}`);
+  }
+  return code;
+}
+
+async function main() {
+  const argv = process.argv.slice(2);
+  if (!argv.length || ["-h", "--help", "help"].includes(argv[0])) { console.log(HELP); return 0; }
+  if (["-v", "--version", "version"].includes(argv[0])) { console.log(VERSION); return 0; }
+  const o = parseArgs(argv);
+  if (o.help) { console.log(HELP); return 0; }
+  switch (o.cmd) {
+    case "claude":
+      return cmdClaude(o);
+    case "serve": {
+      const st = await probe(localBase(o.port));
+      if (st === "agentglow") { console.log(`AgentGlow is already running at ${baseUrl({ port: o.port })}/neural`); return 0; }
+      if (st === "other") fail(`port ${o.port} is in use by something that is not AgentGlow. Pick another one: --port ${o.port + 1}`);
+      return serveForeground({ port: o.port, version: VERSION });
+    }
+    case "stop": {
+      const r = await stopServer(o.port);
+      if (r === "stopped") console.log(`Stopped the AgentGlow server on port ${o.port}.`);
+      else if (r === "not-ours") console.log(`The AgentGlow server on port ${o.port} was not started by this CLI; stop it where it runs.`);
+      else console.log(`No AgentGlow server on port ${o.port}.`);
+      return 0;
+    }
+    case "open": {
+      const url = `${remoteUrl() || baseUrl({ port: o.port })}/neural`;
+      openBrowser(url);
+      console.log(url);
+      return 0;
+    }
+    default:
+      console.error(`agentglow: unknown command "${o.cmd}"\n`);
+      console.log(HELP);
+      return 2;
+  }
+}
+
+main().then((code) => process.exit(code ?? 0), (e) => fail(e.message || String(e)));

package/cli/lib/net.mjs

@@ -0,0 +1,73 @@
+// Tiny HTTP helpers on node:http/https (no runtime deps).
+import fs from "node:fs";
+import http from "node:http";
+import https from "node:https";
+import net from "node:net";
+
+function get(url, { timeout = 30000 } = {}) {
+  return new Promise((resolve, reject) => {
+    const mod = url.startsWith("https:") ? https : http;
+    const req = mod.get(url, { headers: { "user-agent": "agentglow-cli" } }, resolve);
+    req.setTimeout(timeout, () => req.destroy(new Error(`timeout fetching ${url}`)));
+    req.on("error", reject);
+  });
+}
+
+/** GET with redirects, streamed to `dest`. */
+export async function download(url, dest, redirects = 8) {
+  const res = await get(url, { timeout: 120000 });
+  if (res.statusCode >= 300 && res.statusCode < 400 && res.headers.location) {
+    res.resume();
+    if (!redirects) throw new Error(`too many redirects for ${url}`);
+    return download(new URL(res.headers.location, url).toString(), dest, redirects - 1);
+  }
+  if (res.statusCode !== 200) {
+    res.resume();
+    throw new Error(`GET ${url} -> HTTP ${res.statusCode}`);
+  }
+  await new Promise((resolve, reject) => {
+    const out = fs.createWriteStream(dest);
+    res.pipe(out);
+    res.on("error", reject);
+    out.on("error", reject);
+    out.on("finish", resolve);
+  });
+}
+
+/** GET a URL, return { status, body } or null on connection error / timeout. */
+export async function fetchText(url, timeout = 2000) {
+  try {
+    const res = await get(url, { timeout });
+    let body = "";
+    res.setEncoding("utf8");
+    for await (const chunk of res) body += chunk;
+    return { status: res.statusCode, body };
+  } catch {
+    return null;
+  }
+}
+
+/** "agentglow" when an AgentGlow server answers /live/health, "other" when something else holds it, else "none". */
+export async function probe(base, timeout = 2000) {
+  const r = await fetchText(base + "/live/health", timeout);
+  if (r) {
+    try { if (r.status === 200 && JSON.parse(r.body).ok === true) return "agentglow"; } catch { /* not ours */ }
+    return "other";
+  }
+  const u = new URL(base);
+  if (!["localhost", "127.0.0.1", "::1", "[::1]"].includes(u.hostname)) return "none";
+  // something may hold the port on only one loopback family (e.g. a dev server on [::1] that `localhost` reaches)
+  const port = Number(u.port || (u.protocol === "https:" ? 443 : 80));
+  const open = await Promise.all([portOpen(port, "127.0.0.1"), portOpen(port, "::1")]);
+  return open.some(Boolean) ? "other" : "none";
+}
+
+export function portOpen(port, host = "127.0.0.1", timeout = 1000) {
+  return new Promise((resolve) => {
+    const s = net.connect({ port, host });
+    const done = (v) => { s.destroy(); resolve(v); };
+    s.setTimeout(timeout, () => done(false));
+    s.on("connect", () => done(true));
+    s.on("error", () => done(false));
+  });
+}

package/cli/lib/server.mjs

@@ -0,0 +1,128 @@
+// Start / stop the Python `agentglow serve` through uv.
+import fs from "node:fs";
+import path from "node:path";
+import { spawn, spawnSync } from "node:child_process";
+import { probe } from "./net.mjs";
+import { cacheDir, findRunner } from "./uv.mjs";
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+export const localBase = (port) => `http://127.0.0.1:${port}`;
+export const pidFile = (port, dir = cacheDir()) => path.join(dir, `server-${port}.pid`);
+export const logFile = (port, dir = cacheDir()) => path.join(dir, `server-${port}.log`);
+
+/** PyPI requirement for the server: same version as this npm package (or AGENTGLOW_PY_SPEC). */
+export function pySpecs(version, env = process.env) {
+  if (env.AGENTGLOW_PY_SPEC) return [env.AGENTGLOW_PY_SPEC];
+  return /^\d+\.\d+\.\d+$/.test(version || "") ? [`agentglow==${version}`, "agentglow"] : ["agentglow"];
+}
+
+export function serveArgv(runner, spec, port) {
+  return [...runner.args, "--from", spec, "agentglow", "serve", "--host", "127.0.0.1", "--port", String(port)];
+}
+
+function alive(pid) {
+  try { process.kill(pid, 0); return true; } catch (e) { return e.code === "EPERM"; }
+}
+
+export function readPid(port) {
+  try {
+    const j = JSON.parse(fs.readFileSync(pidFile(port), "utf8"));
+    return j && alive(j.pid) ? j : null;
+  } catch { return null; }
+}
+
+function tail(file, n = 15) {
+  try { return fs.readFileSync(file, "utf8").trimEnd().split("\n").slice(-n).join("\n"); } catch { return ""; }
+}
+
+/** Start the server in the background and wait for /live/health. Returns { pid, started: true }. */
+export async function startBackground({ port, version, log = console.error, timeoutMs = 120000 }) {
+  const dir = cacheDir();
+  fs.mkdirSync(dir, { recursive: true });
+  const runner = await findRunner({ log });
+  log(`Starting AgentGlow server on port ${port} (via ${runner.source === "uvx" ? "uvx" : "uv"}). ` +
+      "First run downloads Python + agentglow, about 30-60s ...");
+  const logPath = logFile(port);
+  let lastErr = "";
+  for (const spec of pySpecs(version)) {
+    const fd = fs.openSync(logPath, "w");
+    const child = spawn(runner.cmd, serveArgv(runner, spec, port), {
+      detached: true, stdio: ["ignore", fd, fd], windowsHide: true,
+      env: { ...process.env, PYTHONUNBUFFERED: "1" },
+    });
+    fs.closeSync(fd);
+    let exited = null;
+    child.on("exit", (code) => { exited = code ?? -1; });
+    child.on("error", (e) => { exited = -1; lastErr = e.message; });
+    child.unref();
+    fs.writeFileSync(pidFile(port), JSON.stringify({ pid: child.pid, port, spec, startedAt: new Date().toISOString() }));
+    const t0 = Date.now();
+    let noted = false;
+    while (Date.now() - t0 < timeoutMs) {
+      if ((await probe(localBase(port), 1500)) === "agentglow") return { pid: child.pid, started: true };
+      if (exited !== null) break;
+      if (!noted && Date.now() - t0 > 15000) { log("  still preparing the Python environment ..."); noted = true; }
+      await sleep(500);
+    }
+    if (exited === null) {
+      killTree(child.pid);
+      fs.rmSync(pidFile(port), { force: true });
+      throw new Error(`AgentGlow server did not become healthy within ${timeoutMs / 1000}s. Log: ${logPath}\n${tail(logPath)}`);
+    }
+    fs.rmSync(pidFile(port), { force: true });
+    lastErr = tail(logPath) || lastErr;
+    log(`  ${spec} failed to start, ${spec === "agentglow" ? "giving up" : "retrying with the latest agentglow"} ...`);
+  }
+  throw new Error(`AgentGlow server failed to start. Log: ${logPath}\n${lastErr}`);
+}
+
+export function killTree(pid) {
+  if (process.platform === "win32") {
+    spawnSync("taskkill", ["/T", "/F", "/PID", String(pid)], { stdio: "ignore" });
+    return;
+  }
+  try { process.kill(-pid, "SIGTERM"); } catch { try { process.kill(pid, "SIGTERM"); } catch { /* gone */ } }
+}
+
+/** Stop a server this CLI started. Returns "stopped" | "not-ours" | "none". */
+export async function stopServer(port) {
+  const info = readPid(port);
+  if (!info) {
+    fs.rmSync(pidFile(port), { force: true });
+    return (await probe(localBase(port), 1500)) === "agentglow" ? "not-ours" : "none";
+  }
+  killTree(info.pid);
+  for (let i = 0; i < 20 && alive(info.pid); i++) await sleep(250);
+  if (alive(info.pid) && process.platform !== "win32") { try { process.kill(-info.pid, "SIGKILL"); } catch { /* gone */ } }
+  fs.rmSync(pidFile(port), { force: true });
+  return "stopped";
+}
+
+/** Run the server in the foreground (stdio inherited). Resolves with its exit code. */
+export async function serveForeground({ port, version, log = console.error }) {
+  const runner = await findRunner({ log });
+  const specs = pySpecs(version);
+  for (const [i, spec] of specs.entries()) {
+    const t0 = Date.now();
+    const code = await new Promise((resolve) => {
+      const child = spawn(runner.cmd, serveArgv(runner, spec, port), { stdio: "inherit" });
+      const fwd = (sig) => () => child.kill(sig);
+      const onInt = fwd("SIGINT"), onTerm = fwd("SIGTERM");
+      process.on("SIGINT", onInt);
+      process.on("SIGTERM", onTerm);
+      child.on("exit", (c, sig) => {
+        process.off("SIGINT", onInt);
+        process.off("SIGTERM", onTerm);
+        resolve(c ?? (sig ? 130 : 1));
+      });
+    });
+    // a pinned version missing on PyPI fails fast; fall back to latest once
+    if (code !== 0 && i < specs.length - 1 && Date.now() - t0 < 30000) {
+      log(`${spec} failed, retrying with the latest agentglow ...`);
+      continue;
+    }
+    return code;
+  }
+  return 1;
+}

package/cli/lib/settings.mjs

@@ -0,0 +1,192 @@
+// Claude Code settings for AgentGlow: HTTP hooks -> POST /v1/claude-code, OTel traces -> POST /v1/traces.
+// Mirrors examples/claude-code/settings.json (a unit test keeps the two in sync).
+import fs from "node:fs";
+import path from "node:path";
+
+export const HOOK_PATH = "/v1/claude-code";
+export const TRACES_PATH = "/v1/traces";
+
+// [event, needs "matcher": "*"] in the order of examples/claude-code/settings.json
+export const HOOK_EVENTS = [
+  ["SessionStart", false],
+  ["UserPromptSubmit", false],
+  ["PreToolUse", true],
+  ["PostToolUse", true],
+  ["PostToolUseFailure", true],
+  ["SubagentStart", true],
+  ["SubagentStop", true],
+  ["Stop", false],
+  ["SessionEnd", false],
+];
+
+// Static env values; OTEL_EXPORTER_OTLP_TRACES_ENDPOINT is added per base URL.
+export const STATIC_ENV = {
+  CLAUDE_CODE_ENABLE_TELEMETRY: "1",
+  CLAUDE_CODE_ENHANCED_TELEMETRY_BETA: "1",
+  OTEL_TRACES_EXPORTER: "otlp",
+  OTEL_EXPORTER_OTLP_PROTOCOL: "http/json",
+};
+const ENDPOINT_KEY = "OTEL_EXPORTER_OTLP_TRACES_ENDPOINT";
+const TAIL_ENV = { OTEL_TRACES_EXPORT_INTERVAL: "1000", OTEL_LOG_USER_PROMPTS: "0" };
+
+export function baseUrl({ port = 8100, url } = {}) {
+  return String(url || `http://localhost:${port}`).replace(/\/+$/, "");
+}
+
+export function envBlock(base) {
+  return { ...STATIC_ENV, [ENDPOINT_KEY]: base + TRACES_PATH, ...TAIL_ENV };
+}
+
+function hookGroup(base, withMatcher) {
+  const hook = {
+    type: "http",
+    url: base + HOOK_PATH,
+    timeout: 2,
+    async: true,
+    headers: { "x-api-key": "$AGENTGLOW_API_KEY" },
+    allowedEnvVars: ["AGENTGLOW_API_KEY"],
+  };
+  return withMatcher ? { matcher: "*", hooks: [hook] } : { hooks: [hook] };
+}
+
+/** The full settings object (what `claude --settings <file>` gets). */
+export function claudeSettings(base) {
+  const hooks = {};
+  for (const [event, m] of HOOK_EVENTS) hooks[event] = [hookGroup(base, m)];
+  return { env: envBlock(base), hooks };
+}
+
+export function isOurHook(h) {
+  return !!h && h.type === "http" && typeof h.url === "string" && h.url.includes(HOOK_PATH);
+}
+
+/** Base URLs of our hooks found in a settings object (used to recognise our traces endpoint). */
+export function ourBases(settings) {
+  const out = new Set();
+  for (const groups of Object.values(settings?.hooks || {})) {
+    if (!Array.isArray(groups)) continue;
+    for (const g of groups) for (const h of g?.hooks || []) {
+      if (isOurHook(h)) out.add(h.url.slice(0, h.url.indexOf(HOOK_PATH)));
+    }
+  }
+  return [...out];
+}
+
+const clone = (o) => JSON.parse(JSON.stringify(o ?? {}));
+
+/**
+ * Remove exactly our hook entries and our env keys. `state.addedEnv` (from the install sidecar) lists the env keys
+ * we added; without it, keys are removed only when their value is the one we would have set.
+ */
+export function unmergeSettings(settings, state = null) {
+  const s = clone(settings);
+  const bases = ourBases(s);
+  if (s.hooks && typeof s.hooks === "object") {
+    for (const [event, groups] of Object.entries(s.hooks)) {
+      if (!Array.isArray(groups)) continue;
+      const kept = [];
+      for (const g of groups) {
+        if (!g || !Array.isArray(g.hooks)) { kept.push(g); continue; }
+        const hooks = g.hooks.filter((h) => !isOurHook(h));
+        if (hooks.length === g.hooks.length) kept.push(g);
+        else if (hooks.length) kept.push({ ...g, hooks });
+      }
+      if (kept.length) s.hooks[event] = kept;
+      else delete s.hooks[event];
+    }
+    if (!Object.keys(s.hooks).length) delete s.hooks;
+  }
+  if (s.env && typeof s.env === "object") {
+    const ours = { ...STATIC_ENV, ...TAIL_ENV };
+    const endpoints = new Set(bases.map((b) => b + TRACES_PATH));
+    const candidates = state?.addedEnv ?? [...Object.keys(ours), ENDPOINT_KEY];
+    for (const k of candidates) {
+      if (!(k in s.env)) continue;
+      const v = s.env[k];
+      const mine = k === ENDPOINT_KEY ? (state?.addedEnv ? true : endpoints.has(v)) : (state?.addedEnv ? true : v === ours[k]);
+      if (mine) delete s.env[k];
+    }
+    if (!Object.keys(s.env).length) delete s.env;
+  }
+  return s;
+}
+
+/**
+ * Add our hooks + env to `settings` (idempotent: our previous entries are replaced, foreign ones kept).
+ * Env keys the user already set to a different value are left alone and reported in `skipped`.
+ * Returns { settings, state: { addedEnv, base }, skipped }.
+ */
+export function mergeSettings(settings, base, state = null) {
+  const s = unmergeSettings(settings, state);
+  const ours = claudeSettings(base);
+  s.hooks = s.hooks && typeof s.hooks === "object" ? s.hooks : {};
+  for (const [event, groups] of Object.entries(ours.hooks)) {
+    s.hooks[event] = [...(Array.isArray(s.hooks[event]) ? s.hooks[event] : []), ...groups];
+  }
+  s.env = s.env && typeof s.env === "object" ? s.env : {};
+  const addedEnv = [];
+  const skipped = [];
+  for (const [k, v] of Object.entries(ours.env)) {
+    if (!(k in s.env)) { s.env[k] = v; addedEnv.push(k); }
+    else if (s.env[k] !== v) skipped.push(k);
+  }
+  if (!Object.keys(s.env).length) delete s.env;
+  return { settings: s, state: { base, addedEnv }, skipped };
+}
+
+// ---------- files ----------
+
+export function statePath(settingsFile) {
+  return path.join(path.dirname(settingsFile), "agentglow-install.json");
+}
+
+function readJson(file, fallback) {
+  try { return JSON.parse(fs.readFileSync(file, "utf8")); }
+  catch (e) {
+    if (e.code === "ENOENT") return fallback;
+    throw new Error(`could not parse ${file}: ${e.message}`);
+  }
+}
+
+function backup(file, now) {
+  if (!fs.existsSync(file)) return null;
+  const ts = new Date(now).toISOString().replace(/[:.]/g, "-");
+  const dest = `${file}.agentglow-backup-${ts}`;
+  fs.copyFileSync(file, dest);
+  return dest;
+}
+
+const same = (a, b) => JSON.stringify(a) === JSON.stringify(b);
+
+/** Merge into a settings file. Returns { changed, backup, skipped, file }. */
+export function installSettingsFile(file, base, { now = Date.now() } = {}) {
+  const before = readJson(file, {});
+  const st = readJson(statePath(file), null);
+  const { settings, state, skipped } = mergeSettings(before, base, st);
+  if (same(before, settings) && st && same(st.addedEnv, state.addedEnv)) {
+    return { changed: false, backup: null, skipped, file };
+  }
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const bak = same(before, settings) ? null : backup(file, now);
+  if (!same(before, settings)) fs.writeFileSync(file, JSON.stringify(settings, null, 2) + "\n");
+  fs.writeFileSync(statePath(file), JSON.stringify(state, null, 2) + "\n");
+  return { changed: true, backup: bak, skipped, file };
+}
+
+/** Remove our entries from a settings file. Returns { changed, backup, file }. */
+export function uninstallSettingsFile(file, { now = Date.now() } = {}) {
+  const before = readJson(file, null);
+  const st = readJson(statePath(file), null);
+  if (before === null) {
+    if (st) fs.rmSync(statePath(file), { force: true });
+    return { changed: false, backup: null, file };
+  }
+  const after = unmergeSettings(before, st);
+  let bak = null;
+  if (!same(before, after)) {
+    bak = backup(file, now);
+    fs.writeFileSync(file, JSON.stringify(after, null, 2) + "\n");
+  }
+  fs.rmSync(statePath(file), { force: true });
+  return { changed: !same(before, after), backup: bak, file };
+}