agentglow 0.2.3 → 0.2.5

package/README.md

@@ -11,16 +11,20 @@ Python server, so it works with LangGraph, deepagents, LangChain and anything el
 ## Watch Claude Code (CLI)
 
 ```bash
-npx agentglow claude
+npx agentglow setup        # once
+claude                     # then just use Claude Code as usual
 ```
-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.
+`setup` adds AgentGlow hooks + traces to `~/.claude/settings.json` (backup first) plus a hook that auto-starts the
+AgentGlow server with every `claude` session, then opens the 3D view. Only Node 18+ is needed (uv + Python are fetched
+on first run). Your agents and subagents appear live at http://localhost:8100/neural 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 |
+| `npx agentglow setup [--port 8100]` | install once (backup first), start the server, open `/neural` |
+| `npx agentglow status` / `open` / `stop` | check install + server / open the view / stop the background server |
+| `npx agentglow remove` | uninstall everything `setup` added and stop the server |
+| `npx agentglow start [--background]` | run the server yourself (`serve` is an alias) |
+| `npx agentglow claude [-- <claude args>]` | try it without installing: one session with temporary settings |
 
 `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).

package/cli/agentglow.mjs

@@ -1,59 +1,71 @@
 #!/usr/bin/env node
-// agentglow CLI: watch Claude Code in 3D with one command. Needs only Node >= 18 (uv + Python are fetched on demand).
+// agentglow CLI: set up once, then every `claude` session shows up in 3D. 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 { fetchText, probe } from "./lib/net.mjs";
+import {
+  baseUrl, claudeSettings, installSettingsFile, isOurHook, readState, startHookCommand, uninstallSettingsFile,
+} from "./lib/settings.mjs";
+import {
+  clearLock, installCliCopy, localBase, readLock, readPid, removeCliCopies, serveForeground, spawnStarter,
+  startBackground, stopServer,
+} from "./lib/server.mjs";
 import { which } from "./lib/uv.mjs";
 
-const here = path.dirname(fileURLToPath(import.meta.url));
+const SELF = fileURLToPath(import.meta.url);
+const here = path.dirname(SELF);
 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
+const HELP = `agentglow ${VERSION}: watch Claude Code agents in 3D
+
+  npx agentglow setup [--port 8100]   (recommended) set up once: hooks in ~/.claude/settings.json,
+                                      server auto-starts with every \`claude\` session
+  npx agentglow status                server health, port, pid, whether hooks are installed
+  npx agentglow open                  open the 3D view (http://localhost:8100/neural)
+  npx agentglow stop                  stop the background server
+  npx agentglow remove                undo setup: remove the hooks and stop the server
+  npx agentglow claude [-- <args>]    try it without installing: one claude session with AgentGlow
+
+More: npx agentglow start [--background] [--port N]   (serve = start in the foreground)
+Env:  AGENTGLOW_URL (remote server), AGENTGLOW_API_KEY (ingest key), AGENTGLOW_CACHE_DIR
 `;
 
+const DEFAULT_PORT = 8100;
+
 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 envPort = Number(process.env.AGENTGLOW_PORT);
+  const o = {
+    cmd: argv[0], port: envPort || DEFAULT_PORT, portSet: !!envPort, open: true, install: false, uninstall: false,
+    background: false, quiet: 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 === "--port") { o.port = Number(args[++i]); o.portSet = true; }
+    else if (a.startsWith("--port=")) { o.port = Number(a.slice(7)); o.portSet = true; }
     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 === "--background" || a === "-b") o.background = true;
+    else if (a === "--quiet" || a === "-q") o.quiet = 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");
+  if (!Number.isInteger(o.port) || o.port < 1 || o.port > 65535) {
+    if (o.quiet) process.exit(0);
+    fail("--port must be a number between 1 and 65535");
+  }
   return o;
 }
 
@@ -69,8 +81,37 @@ function openBrowser(url) {
 }
 
 const remoteUrl = () => (process.env.AGENTGLOW_URL || "").replace(/\/+$/, "") || null;
+const settingsFile = () => path.join(process.env.CLAUDE_CONFIG_DIR || path.join(os.homedir(), ".claude"), "settings.json");
+const portFlag = (port) => (port !== DEFAULT_PORT ? ` --port ${port}` : "");
+
+/** --port when given, else the port `setup` used, else 8100. */
+function effectivePort(o) {
+  if (o.portSet) return o.port;
+  try { return readState(settingsFile())?.port || o.port; } catch { return o.port; }
+}
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
 
-/** Make sure a server answers; returns { base (for hooks + browser), started }. */
+/** Start the local server in the background (or reuse it) and wait until healthy. */
+async function startLocal(port, { ignoreLock = false } = {}) {
+  const pending = () => readPid(port) || (!ignoreLock && readLock(port));
+  const st = await probe(localBase(port));
+  if (st === "agentglow") return { started: false };
+  if (st === "other") throw new Error(`port ${port} is in use by something that is not AgentGlow. Pick another one: --port ${port + 1}`);
+  if (pending()) {
+    // another `start` (e.g. the SessionStart hook) is already bringing it up
+    console.error(`AgentGlow is starting on port ${port} ...`);
+    for (let t0 = Date.now(); Date.now() - t0 < 120000; await sleep(500)) {
+      if ((await probe(localBase(port), 1500)) === "agentglow") return { started: true };
+      if (!pending()) break;
+    }
+    if ((await probe(localBase(port), 1500)) === "agentglow") return { started: true };
+  }
+  const r = await startBackground({ port, version: VERSION });
+  return { started: true, pid: r.pid };
+}
+
+/** Make sure a server answers; returns { base (for hooks + browser), started }. Used by `claude` try mode. */
 async function ensureServer(port) {
   const remote = remoteUrl();
   if (remote) {
@@ -78,30 +119,155 @@ async function ensureServer(port) {
     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 };
+  try {
+    const { started } = await startLocal(port);
+    return { base: baseUrl({ port }), started };
+  } catch (e) { fail(e.message); }
 }
 
-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;
+// ---------- setup / remove ----------
+
+function nodeForHook() {
+  // a PATH node survives Homebrew / nvm patch upgrades better than the versioned execPath
+  return which("node") || process.execPath;
+}
+
+async function cmdSetup(o) {
+  const file = settingsFile();
+  const remote = remoteUrl();
+  const port = o.port;
+  const base = remote || baseUrl({ port });
+  let startCommand = null;
+  if (!remote) {
+    const script = installCliCopy({ srcCliDir: here, version: VERSION });
+    startCommand = startHookCommand({
+      port, version: VERSION, node: nodeForHook(), script, cacheDir: process.env.AGENTGLOW_CACHE_DIR,
+    });
+  }
+  const r = installSettingsFile(file, base, { startCommand, extra: remote ? {} : { port } });
+  if (!r.changed) console.log(`AgentGlow hooks are already in ${file} (${base}).`);
+  else console.log(`Added AgentGlow hooks + traces env to ${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".');
+
+  const view = `${base}/neural`;
+  if (remote) {
+    if ((await probe(remote, 4000)) !== "agentglow") console.error(`agentglow: warning: ${remote}/live/health did not answer like AgentGlow.`);
+  } else {
+    try {
+      const s = await startLocal(port);
+      console.log(s.started ? `Started the AgentGlow server on port ${port}.` : `AgentGlow server already running on port ${port}.`);
+    } catch (e) {
+      console.error(`agentglow: ${e.message}`);
+      console.error(`The hooks are installed; start the server with: npx agentglow start --background${portFlag(port)}`);
+      return 1;
     }
-    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");
+  }
+  if (o.open) openBrowser(view);
+  console.log(`\nDone. Just run \`claude\` as usual. View: ${view}  Undo: npx agentglow remove`);
+  return 0;
+}
+
+async function cmdRemove(o) {
+  const file = settingsFile();
+  const r = uninstallSettingsFile(file);
+  const st = r.state;
+  if (r.changed) {
+    console.log(`Removed the AgentGlow hooks + env from ${file}.`);
+    console.log(`  Settings as they were just now: ${r.backup}`);
+    if (st?.backup) console.log(`  Settings from before setup:     ${st.backup}  (restore: cp "${st.backup}" "${file}")`);
+  } else console.log(`No AgentGlow entries in ${file}.`);
+  const port = o.portSet ? o.port : st?.port || o.port;
+  if (!remoteUrl() && (st?.startHook || !st)) {
+    const s = await stopServer(port);
+    if (s === "stopped") console.log(`Stopped the AgentGlow server on port ${port}.`);
+    else if (s === "not-ours") console.log(`An AgentGlow server on port ${port} was not started by this CLI; left it running.`);
+  }
+  try { removeCliCopies(); } catch { /* ignore */ }
+  return 0;
+}
+
+// ---------- start / stop / status ----------
+
+/** The SessionStart hook: no output (stdout would go into Claude's context), never fails, returns fast. */
+async function cmdStartQuiet(o) {
+  setTimeout(() => process.exit(0), 3000).unref();
+  try {
+    if (remoteUrl()) return 0;
+    if ((await probe(localBase(o.port), 800)) !== "none") return 0; // running, or the port is taken
+    spawnStarter({ port: o.port, script: SELF });
+  } catch { /* never block Claude */ }
+  return 0;
+}
+
+async function cmdStart(o) {
+  if (o.quiet) return cmdStartQuiet(o);
+  const port = effectivePort(o);
+  if (!o.background) {
+    const st = await probe(localBase(port));
+    if (st === "agentglow") { console.log(`AgentGlow is already running at ${baseUrl({ port })}/neural`); return 0; }
+    if (st === "other") fail(`port ${port} is in use by something that is not AgentGlow. Pick another one: --port ${port + 1}`);
+    return serveForeground({ port, version: VERSION });
+  }
+  const starter = process.env.AGENTGLOW_STARTER === "1";
+  try {
+    const s = await startLocal(port, { ignoreLock: starter });
+    const pid = readPid(port)?.pid;
+    console.log(`AgentGlow ${s.started ? "started" : "is already running"} at ${baseUrl({ port })}/neural${pid ? ` (pid ${pid})` : ""}.`);
+    if (!starter) console.log(`Stop it with: npx agentglow stop${portFlag(port)}`);
     return 0;
+  } catch (e) {
+    console.error(`agentglow: ${e.message}`);
+    return 1;
+  } finally {
+    if (starter) clearLock(port);
+  }
+}
+
+async function cmdStatus(o) {
+  const file = settingsFile();
+  const port = effectivePort(o);
+  const remote = remoteUrl();
+  let state = null;
+  let installed = false;
+  let startHook = false;
+  try {
+    state = readState(file);
+    const s = JSON.parse(fs.readFileSync(file, "utf8"));
+    for (const groups of Object.values(s.hooks || {})) {
+      for (const g of Array.isArray(groups) ? groups : []) {
+        for (const h of g?.hooks || []) {
+          if (!isOurHook(h)) continue;
+          if (h.type === "command") startHook = true;
+          else installed = true;
+        }
+      }
+    }
+  } catch { /* no settings file */ }
+  const base = remote || state?.base || baseUrl({ port });
+  const h = await fetchText(base + "/live/health", 2000);
+  let health = null;
+  try { health = h && h.status === 200 ? JSON.parse(h.body) : null; } catch { /* not ours */ }
+  const pid = remote ? null : readPid(port)?.pid;
+  const starting = !remote && !health && readLock(port);
+  console.log(`agentglow CLI ${VERSION}`);
+  console.log(`server:  ${health?.ok ? `healthy at ${base} (server ${health.version || "?"})` : starting ? `starting on port ${port}` : `not running at ${base}`}`);
+  if (!remote) console.log(`port:    ${port}${pid ? `  pid ${pid} (started by this CLI)` : ""}`);
+  console.log(`hooks:   ${installed ? `installed in ${file}${startHook ? " (server auto-starts with claude)" : ""}` : "not installed (run: npx agentglow setup)"}`);
+  if (health?.ok) console.log(`view:    ${base}/neural`);
+  return 0;
+}
+
+// ---------- try mode ----------
+
+async function cmdClaude(o) {
+  if (o.install) {
+    console.error("agentglow: `claude --install` is deprecated; use `npx agentglow setup`.");
+    return cmdSetup(o);
+  }
+  if (o.uninstall) {
+    console.error("agentglow: `claude --uninstall` is deprecated; use `npx agentglow remove`.");
+    return cmdRemove(o);
   }
 
   const claude = which("claude");
@@ -134,7 +300,7 @@ async function cmdClaude(o) {
   });
   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}` : ""}`);
+    console.error(`AgentGlow is still running at ${view}. Stop it with: npx agentglow stop${portFlag(o.port)}`);
   }
   return code;
 }
@@ -144,25 +310,31 @@ async function main() {
   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; }
+  if (o.help && !o.quiet) { console.log(HELP); return 0; }
   switch (o.cmd) {
+    case "setup":
+      return cmdSetup(o);
+    case "remove":
+    case "uninstall":
+      return cmdRemove(o);
     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 "start":
+      return cmdStart(o);
+    case "serve":
+      return cmdStart({ ...o, background: false, quiet: false });
+    case "status":
+      return cmdStatus(o);
     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}.`);
+      const port = effectivePort(o);
+      const r = await stopServer(port);
+      if (r === "stopped") console.log(`Stopped the AgentGlow server on port ${port}.`);
+      else if (r === "not-ours") console.log(`The AgentGlow server on port ${port} was not started by this CLI; stop it where it runs.`);
+      else console.log(`No AgentGlow server on port ${port}.`);
       return 0;
     }
     case "open": {
-      const url = `${remoteUrl() || baseUrl({ port: o.port })}/neural`;
+      const url = `${remoteUrl() || baseUrl({ port: effectivePort(o) })}/neural`;
       openBrowser(url);
       console.log(url);
       return 0;
@@ -174,4 +346,7 @@ async function main() {
   }
 }
 
-main().then((code) => process.exit(code ?? 0), (e) => fail(e.message || String(e)));
+main().then((code) => process.exit(code ?? 0), (e) => {
+  if (process.argv.includes("--quiet") || process.argv.includes("-q")) process.exit(0);
+  fail(e.message || String(e));
+});

package/cli/lib/server.mjs

@@ -10,6 +10,8 @@ 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`);
+export const lockFile = (port, dir = cacheDir()) => path.join(dir, `server-${port}.starting`);
+const LOCK_TTL_MS = 180000;
 
 /** PyPI requirement for the server: same version as this npm package (or AGENTGLOW_PY_SPEC). */
 export function pySpecs(version, env = process.env) {
@@ -21,7 +23,7 @@ export function serveArgv(runner, spec, port) {
   return [...runner.args, "--from", spec, "agentglow", "serve", "--host", "127.0.0.1", "--port", String(port)];
 }
 
-function alive(pid) {
+export function alive(pid) {
   try { process.kill(pid, 0); return true; } catch (e) { return e.code === "EPERM"; }
 }
 
@@ -87,10 +89,13 @@ export function killTree(pid) {
 
 /** Stop a server this CLI started. Returns "stopped" | "not-ours" | "none". */
 export async function stopServer(port) {
+  const starter = readLock(port);
+  if (starter) { killTree(starter.pid); clearLock(port); }
   const info = readPid(port);
   if (!info) {
     fs.rmSync(pidFile(port), { force: true });
-    return (await probe(localBase(port), 1500)) === "agentglow" ? "not-ours" : "none";
+    if ((await probe(localBase(port), 1500)) === "agentglow") return "not-ours";
+    return starter ? "stopped" : "none";
   }
   killTree(info.pid);
   for (let i = 0; i < 20 && alive(info.pid); i++) await sleep(250);
@@ -99,6 +104,62 @@ export async function stopServer(port) {
   return "stopped";
 }
 
+/** A detached starter (see spawnStarter) that is still preparing the server, or null. */
+export function readLock(port) {
+  try {
+    const j = JSON.parse(fs.readFileSync(lockFile(port), "utf8"));
+    return j && alive(j.pid) && Date.now() - j.at < LOCK_TTL_MS ? j : null;
+  } catch { return null; }
+}
+
+/**
+ * Fire-and-forget start for the SessionStart hook: spawn `node <cli> start --background --port <p>` detached
+ * (it waits for health, falls back to the latest PyPI version and logs to the server log) and return at once.
+ * A lockfile keeps two sessions starting at the same moment from racing. Returns the starter pid or null.
+ */
+export function spawnStarter({ port, script, node = process.execPath }) {
+  if (readPid(port) || readLock(port)) return null;
+  const dir = cacheDir();
+  fs.mkdirSync(dir, { recursive: true });
+  const fd = fs.openSync(logFile(port), "a");
+  const child = spawn(node, [script, "start", "--background", "--port", String(port)], {
+    detached: true, stdio: ["ignore", fd, fd], windowsHide: true,
+    env: { ...process.env, AGENTGLOW_STARTER: "1" },
+  });
+  fs.closeSync(fd);
+  child.on("error", () => {});
+  child.unref();
+  fs.writeFileSync(lockFile(port), JSON.stringify({ pid: child.pid, at: Date.now() }));
+  return child.pid;
+}
+
+export function clearLock(port) {
+  fs.rmSync(lockFile(port), { force: true });
+}
+
+/**
+ * Copy this CLI (plain .mjs files, Node builtins only) to <cache>/cli/<version>/ so the SessionStart hook can run it
+ * with plain `node` instead of resolving npx every session. Returns the copied entry script.
+ */
+export function installCliCopy({ srcCliDir, version }) {
+  const root = path.join(cacheDir(), "cli", version || "dev");
+  const tmp = `${root}.tmp-${process.pid}`;
+  fs.rmSync(tmp, { recursive: true, force: true });
+  fs.mkdirSync(path.join(tmp, "cli", "lib"), { recursive: true });
+  fs.copyFileSync(path.join(srcCliDir, "agentglow.mjs"), path.join(tmp, "cli", "agentglow.mjs"));
+  for (const f of fs.readdirSync(path.join(srcCliDir, "lib"))) {
+    if (f.endsWith(".mjs")) fs.copyFileSync(path.join(srcCliDir, "lib", f), path.join(tmp, "cli", "lib", f));
+  }
+  fs.writeFileSync(path.join(tmp, "package.json"), JSON.stringify({ name: "agentglow", version, type: "module" }) + "\n");
+  fs.rmSync(root, { recursive: true, force: true });
+  fs.renameSync(tmp, root);
+  return path.join(root, "cli", "agentglow.mjs");
+}
+
+export function removeCliCopies() {
+  fs.rmSync(path.join(cacheDir(), "cli"), { recursive: true, force: true });
+}
+
 /** 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 });

package/cli/lib/settings.mjs

@@ -56,8 +56,35 @@ export function claudeSettings(base) {
   return { env: envBlock(base), hooks };
 }
 
+// Marker in the SessionStart command hook that starts the server; recognises it on remove / re-setup.
+export const START_MARK = "start --background --quiet";
+
+const isOurHttpHook = (h) => !!h && h.type === "http" && typeof h.url === "string" && h.url.includes(HOOK_PATH);
+const isOurStartHook = (h) =>
+  !!h && h.type === "command" && typeof h.command === "string" && h.command.includes("agentglow") && h.command.includes(START_MARK);
+
 export function isOurHook(h) {
-  return !!h && h.type === "http" && typeof h.url === "string" && h.url.includes(HOOK_PATH);
+  return isOurHttpHook(h) || isOurStartHook(h);
+}
+
+const shq = (s) => `"${String(s).replace(/(["\\$`])/g, "\\$1")}"`;
+
+/**
+ * Shell command for the SessionStart hook that makes sure the local server runs. Prints nothing (SessionStart stdout
+ * would land in Claude's context) and always exits 0. Calls the CLI copy in the cache directly (~30 ms) and falls
+ * back to the pinned npm version through npx (~0.5 s when cached). Windows without Git Bash runs it in PowerShell,
+ * so there it is npx only.
+ */
+export function startHookCommand({ port, version, node, script, cacheDir: dir, platform = process.platform }) {
+  const args = `${START_MARK} --port ${port}`;
+  const npx = `npx -y agentglow${version ? `@${version}` : ""} ${args}`;
+  if (platform === "win32" || !node || !script) return npx;
+  const env = dir ? `AGENTGLOW_CACHE_DIR=${shq(dir)} ` : "";
+  return `${env}${shq(node)} ${shq(script)} ${args} || ${env}${npx}`;
+}
+
+export function startHookGroup(command) {
+  return { hooks: [{ type: "command", command, timeout: 10 }] };
 }
 
 /** Base URLs of our hooks found in a settings object (used to recognise our traces endpoint). */
@@ -66,7 +93,7 @@ export function ourBases(settings) {
   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)));
+      if (isOurHttpHook(h)) out.add(h.url.slice(0, h.url.indexOf(HOOK_PATH)));
     }
   }
   return [...out];
@@ -114,11 +141,13 @@ export function unmergeSettings(settings, state = null) {
 /**
  * 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 }.
+ * `startCommand` adds the SessionStart command hook that starts the local server (see startHookCommand).
+ * Returns { settings, state: { addedEnv, base, startHook }, skipped }.
  */
-export function mergeSettings(settings, base, state = null) {
+export function mergeSettings(settings, base, state = null, { startCommand = null } = {}) {
   const s = unmergeSettings(settings, state);
   const ours = claudeSettings(base);
+  if (startCommand) ours.hooks.SessionStart.unshift(startHookGroup(startCommand));
   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];
@@ -131,7 +160,7 @@ export function mergeSettings(settings, base, state = null) {
     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 };
+  return { settings: s, state: { base, addedEnv, startHook: !!startCommand }, skipped };
 }
 
 // ---------- files ----------
@@ -157,29 +186,40 @@ function backup(file, now) {
 }
 
 const same = (a, b) => JSON.stringify(a) === JSON.stringify(b);
+const sorted = (o) => Object.fromEntries(Object.entries(o || {}).sort(([a], [b]) => a.localeCompare(b)));
 
 /** Merge into a settings file. Returns { changed, backup, skipped, file }. */
-export function installSettingsFile(file, base, { now = Date.now() } = {}) {
+export function installSettingsFile(file, base, { now = Date.now(), startCommand = null, extra = {} } = {}) {
   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)) {
+  const merged = mergeSettings(before, base, st, { startCommand });
+  const { settings, skipped } = merged;
+  const state = { ...merged.state, ...extra };
+  // keep the first backup we made, so `remove` can point at the pre-AgentGlow settings
+  if (st?.backup && !state.backup) state.backup = st.backup;
+  if (same(before, settings) && st && same(sorted({ ...st, backup: state.backup }), sorted(state))) {
     return { changed: false, backup: null, skipped, file };
   }
   fs.mkdirSync(path.dirname(file), { recursive: true });
   const bak = same(before, settings) ? null : backup(file, now);
+  if (bak && !state.backup) state.backup = bak;
   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 }. */
+/** Read the install sidecar (null when AgentGlow is not installed in `file`). */
+export function readState(file) {
+  return readJson(statePath(file), null);
+}
+
+/** Remove our entries from a settings file. Returns { changed, backup, file, state }. */
 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 };
+    return { changed: false, backup: null, file, state: st };
   }
   const after = unmergeSettings(before, st);
   let bak = null;
@@ -188,5 +228,5 @@ export function uninstallSettingsFile(file, { now = Date.now() } = {}) {
     fs.writeFileSync(file, JSON.stringify(after, null, 2) + "\n");
   }
   fs.rmSync(statePath(file), { force: true });
-  return { changed: !same(before, after), backup: bak, file };
+  return { changed: !same(before, after), backup: bak, file, state: st };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentglow",
-  "version": "0.2.3",
+  "version": "0.2.5",
   "description": "Live 3D views of agent systems (LangGraph, deepagents, any OpenTelemetry-instrumented agents) as a React component.",
   "keywords": [
     "claude-code",