nearly-cli 0.1.3 → 0.1.6

package/README.md

@@ -22,9 +22,96 @@ Watch the first thirty seconds. The cover says what the diff cannot: an action t
 
 ## What it needs
 
-Node 18 or newer, Claude Code signed in, and git. No dependencies and no API key: agents run on your existing Claude subscription.
+Node 18 or newer, git, and one of the seven coding agents below signed in. No dependencies and no API key of its own: agents run on whatever subscription you already have.
+
+### Platforms
+
+The suite runs on every push against macOS, Linux and Windows, on Node 18 and 22.
+
+| | macOS | Linux | Windows |
+|---|---|---|---|
+| Gate, recording, records | tested in CI | tested in CI | tested in CI |
+| Turning it on and off | tested in CI | tested in CI | tested in CI |
+| Updating itself | tested in CI | tested in CI | tested in CI |
+| Driving a real agent end to end | **run by hand** | not yet | not yet |
+| Handing the record over at `git push` | **run by hand** | not yet | not yet |
+| Spoken narration | yes | no | no |
+
+Narration uses the built-in `say`, so it is macOS only. Everywhere else the
+record is built identically and reads from its captions, or you can record the
+lines yourself with `--voice-dir`.
+
+The bottom two rows are the honest gap: CI proves the pieces work on all three,
+but a whole session with a real agent, and a real push through the hook, have
+only been done on macOS. If you are the first to try either on Windows or Linux,
+an issue with what broke would be genuinely useful.
+
+### Agents
+
+The editor is not the question. Claude Code in VS Code, in a JetBrains IDE, in a
+plain terminal or over SSH all read the same `.claude/settings.local.json`, so
+all four are already covered. Neither is the model — the gate sits between the
+agent and your machine, below whichever model is answering.
+
+The harness making the tool calls is the question, because that is what exposes
+the hook. Seven are supported:
+
+| | Config it writes | Holds for a human | Record |
+|---|---|---|---|
+| Claude Code | `.claude/settings.local.json` | yes | full |
+| Cursor | `.cursor/hooks.json` | yes | full |
+| Antigravity | `.agents/hooks.json` | yes | full |
+| GitHub Copilot CLI | `.github/hooks/nearly.json` | yes | full |
+| Gemini CLI | `.gemini/settings.json` | yes | full |
+| Codex CLI | `.codex/hooks.json` | yes | no prompts, one turn |
+| Windsurf | `.windsurf/hooks.json` | until Cascade gives up | shell and file tools only |
+
+`nearly` turns on whichever of these the repo shows signs of, and Claude Code
+either way. `nearly --agent=cursor` forces one, `--agent=all` forces all of them,
+and `nearly agents` prints what is actually wired here.
+
+**One of these rows is not like the others.** Claude Code has been run end to end
+against a live agent. The other six are built from each vendor's published hook
+documentation and tested against payloads copied from it — every adapter has to
+refuse `rm -rf` and have that refusal land in words its harness acts on, or the
+suite fails. That is a good bet. It is not the same as having watched it work,
+and `nearly agents` says so in as many words:
 
-Gating, recording and the record itself work on macOS, Linux and Windows. **Spoken narration is macOS only**, because it uses the built-in `say`. Elsewhere the record is built the same way and reads from its captions, or you can supply your own recordings with `--voice-dir`.
+```
+  Run against a live agent: Claude Code
+  Built to the vendor's published hook spec and tested against payloads
+  copied from it, but never yet run against the real thing:
+    Cursor, Antigravity, GitHub Copilot CLI, Codex CLI, Gemini CLI, Windsurf
+```
+
+If you use one of those six, the most useful thing you can do is try it and open
+an issue saying what broke.
+
+#### What the adapters actually do
+
+The server speaks one dialect. Everything downstream of a hook — the consent
+gradient, the recording, the record page, the PR comment — reads Claude Code's
+shape and nothing else. An adapter is a translation at the edge, about thirty
+lines: their payload in, ours out; our answer in, theirs out.
+
+Two decisions make that small enough to trust. Nearly never asks the harness to
+ask — every one of them can prompt, and we want none of it, because their dialog
+is not the record. We hold the hook open and answer once a human has. And tools
+are matched by shape as well as by name: `run_command`, `shell`,
+`run_terminal_cmd` and `bash` are all Bash, and anything carrying a command
+string is treated as Bash even if nobody here has heard of it — because if it
+isn't, the never-rules don't apply to it and `rm -rf` walks through a gate that
+reports itself as working. Anything still unrecognised falls to `ask`.
+
+The harness's own name for the tool travels with the call, so the record says
+`run_command` where Antigravity said `run_command`, while the rule you set
+applies to every one of them.
+
+#### Not supported
+
+Zed's built-in agent, Aider, Kilo Code, Warp and the hosted builders (Replit,
+Lovable, Bolt, v0) expose no blocking pre-tool hook. There is nothing to attach
+to, and no adapter can change that.
 
 ## Use it on your own repo
 
@@ -34,10 +121,17 @@ One command, in the repo you want recorded.
 npx nearly-cli
 ```
 
+> **`npx` not recognised?** It comes with Node.js, so that error means Node is
+> not installed. Get it from [nodejs.org](https://nodejs.org) or, on Windows,
+> `winget install OpenJS.NodeJS.LTS`. Then **open a new terminal** so it picks up
+> the change, and check with `node --version`. You also need Claude Code signed
+> in: Nearly gates Claude Code sessions and does nothing without one.
+
 ```
 ✓ Nearly is on for my-app
 
-  · every Claude Code session here is gated and recorded
+  · Claude Code sessions here are gated and recorded (run end to end against a live agent)
+  · Cursor sessions here are gated and recorded (built to their published hook spec, not yet run against a live agent)
   · upgrades reach this repo automatically
   · the record is offered when you push
 
@@ -116,7 +210,13 @@ Every tool call passes through an HTTP `PreToolUse` hook to this server, which s
 
 "Allow always" and "Never" turn a decision into a rule for the rest of the run, keyed by tool and first word of the command, or file extension for edits. In lab mode every turn is committed in the agent's worktree by the `Stop` hook, so **Undo turn** is a `git reset --hard HEAD~1`.
 
-Agents in lab mode are real Claude Code sessions (`claude -p`) on your Claude subscription, each in its own git worktree under `workspace/.worktrees/`. No API key, no paid infrastructure, anywhere in this project.
+Agents in lab mode are real Claude Code sessions (`claude -p`) on your Claude
+subscription, each on its own branch in its own git worktree. You pick which
+repo to branch from — the dashboard offers the ones you have turned Nearly on
+for — and the branch starts from that repo's HEAD, so it begins where you
+actually are rather than on some assumed `main`. Worktrees live under
+`~/.nearly/workspace/.worktrees/`, outside the installed package, so upgrading
+never deletes one. No API key, no paid infrastructure, anywhere in this project.
 
 ## What the record actually contains
 
@@ -222,12 +322,16 @@ Claude Code treats a hook that times out, errors, or returns anything other than
 npm test
 ```
 
-41 tests, no dependencies, about 30 seconds. They run on a fresh clone with no
+83 tests, no dependencies, about 50 seconds. They run on a fresh clone with no
 agent, no network and no Claude subscription, because the fixtures are the two
 recorded sessions committed in `recordings/demo`.
 
 What they hold the project to:
 
+- **Every adapter.** That `rm -rf` is refused in all seven harnesses' dialects,
+  that the refusal comes back in words each one acts on, that a session appears
+  from whichever field that harness calls its session id, and that a payload none
+  of them would ever send leaves the agent working rather than hanging.
 - **The consent gradient.** That destructive commands are denied without asking,
   that a never pattern still fires when the command is buried in a chain, that an
   unclassified tool is held rather than allowed, and that "always" for `git status`
@@ -252,17 +356,18 @@ The claim this project makes is testable: a reviewer who sees the session record
 ## Roadmap
 
 - **Read Prempti's audit trail as an input.** Their recording is structured, local, Apache-licensed and covers more than ours. The recap builder reads its own JSONL today; a second reader would let anyone already running Prempti get a session record without changing their gate.
-- **A Cursor adapter.** The server speaks JSON in and JSON out, so a tool that runs a script instead of calling a URL needs about twenty lines of translation. Cursor's `beforeShellExecution` is the first target.
+- **Run the six unverified adapters against their real agents.** They are built to spec and tested against the vendors' own documented payloads, but documentation is not a build. Each one that gets run for real either becomes a verified row or becomes a bug report.
 - **Port the recap player to React.** It is one self-contained page today.
 
 ## Files
 
+- `server/adapters.mjs`, the seven harnesses and the translation at each edge
 - `server/index.mjs`, spawn sessions, hooks, policy, recorder, undo
 - `ui/index.html`, sessions, triage of pending approvals, rules, log
 - `scripts/attach.mjs`, install or remove the hooks in a repo of your own; `scripts/post-recap.mjs`, comment the recap on its PR
 - `scripts/build-recap.mjs` + `ui/recap.template.html`, narrated recap page per session
 - `scripts/publish-pages.mjs`, build the `docs/` folder GitHub Pages serves
 - `scripts/install-push-hook.mjs` + `scripts/push-record.mjs`, hand the branch record over at `git push`
-- `workspace/`, the repo agents work on (seeded with the Tempo demo)
+- `~/.nearly/`, where recordings, records and agent worktrees are kept
 - `recordings/<session>.jsonl`, every event and decision; `recordings/demo/` is committed so the records can be rebuilt from source
 - `STUDY.md`, the protocol for testing whether any of this helps a reviewer

package/bin/nearly.mjs

@@ -6,6 +6,7 @@
 //   nearly open         open the dashboard
 //   nearly record       build the record for the current branch
 //   nearly post         put that record on the pull request
+//   nearly agents       which agents this repo is gated for
 //   nearly voices       list the narration voices you have
 //   nearly server       run the server in the foreground (it self-starts otherwise)
 //   nearly hook <ev>    internal: what the Claude Code hooks call
@@ -34,7 +35,12 @@ const run = async (file, args = []) => {
   process.exit(r.status ?? 0);
 };
 
-const [cmd = 'attach', ...rest] = process.argv.slice(2);
+// A leading flag is not a command. `nearly --agent=cursor` and `nearly --off`
+// are how the docs say to do those things, and both used to land on "Unknown
+// command" because the first argument was read as a subcommand name.
+const argv = process.argv.slice(2);
+const leadingFlag = argv[0]?.startsWith('-') && !['--help', '-h', '--which'].includes(argv[0]);
+const [cmd = 'attach', ...rest] = leadingFlag ? ['attach', ...argv] : argv;
 
 async function main() {
 switch (cmd) {
@@ -68,6 +74,9 @@ switch (cmd) {
   case 'publish':
     return run(s('publish-pages.mjs'), rest);
 
+  case 'agents':
+    return run(s('agents.mjs'), rest);
+
   case 'voices':
     return run(s('build-recap.mjs'), ['--voices']);
 
@@ -92,6 +101,7 @@ switch (cmd) {
   nearly open         open the dashboard
   nearly record       build the record for the current branch
   nearly post         put that record on the pull request
+  nearly agents       which agents this repo is gated for
   nearly voices       list the narration voices you have
   nearly server       run the server in the foreground
 `);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nearly-cli",
-  "version": "0.1.3",
+  "version": "0.1.6",
   "description": "A pull request tells you what changed. Nearly tells you what nearly happened: the commands a human refused, the pushes policy blocked, the turns rolled back.",
   "type": "module",
   "bin": {
@@ -34,6 +34,6 @@
   },
   "homepage": "https://anujpatel06.github.io/nearly/",
   "scripts": {
-    "test": "node --test --test-concurrency=1 test/"
+    "test": "node --test --test-concurrency=1 test/policy.test.mjs test/server.test.mjs test/record.test.mjs test/resilience.test.mjs test/detect.test.mjs test/adapters.test.mjs test/spawn.test.mjs"
   }
 }

package/scripts/agents.mjs

@@ -0,0 +1,61 @@
+// What Nearly can gate, and how much of that is a claim rather than a
+// demonstration.
+//
+//   nearly agents        what this repo is gated for, and what else is possible
+//
+// Printed because the difference matters. An adapter written from a vendor's
+// hook documentation is a reasonable bet; it is not the same thing as having
+// watched an agent be stopped. Saying so is cheap, and the alternative — a tool
+// that reports coverage it has not earned — is the exact failure this project
+// was built to catch.
+
+import { existsSync, readFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { ADAPTERS } from '../server/adapters.mjs';
+import { detect, installed } from './detect.mjs';
+
+const dim = (s) => `\x1b[2m${s}\x1b[0m`;
+const bold = (s) => `\x1b[1m${s}\x1b[0m`;
+const ok = (s) => `\x1b[32m${s}\x1b[0m`;
+
+const repo = resolve(process.argv.slice(2).find((a) => !a.startsWith('--')) || process.cwd());
+const here = new Set(detect(repo).map((d) => d.id));
+const machine = new Set(installed().map((d) => d.id));
+
+// The config file existing proves nothing: Cursor writes .cursor/hooks.json for
+// its own reasons. What proves the gate is wired is our command being inside it.
+// Anything weaker would let this command report coverage it has not got.
+const gated = (a) => {
+  const f = join(repo, a.config);
+  if (!existsSync(f)) return false;
+  try { return /nearly/i.test(readFileSync(f, 'utf8')); } catch { return false; }
+};
+
+const width = Math.max(...ADAPTERS.map((a) => a.name.length));
+const pad = (s) => s + ' '.repeat(width - s.length);
+
+console.log('');
+console.log(`  ${bold('Agents')} ${dim(repo)}`);
+console.log('');
+for (const a of ADAPTERS) {
+  const on = gated(a);
+  const mark = on ? ok('●') : dim('○');
+  const state = on ? 'gated here' : here.has(a.id) ? 'used here, not gated' : machine.has(a.id) ? 'installed, unused here' : 'not in use here';
+  console.log(`  ${mark} ${bold(pad(a.name))}  ${pad2(state)} ${dim(a.config)}`);
+}
+function pad2(s) { return s + ' '.repeat(Math.max(0, 22 - s.length)); }
+
+console.log('');
+const proven = ADAPTERS.filter((a) => a.verified);
+const claimed = ADAPTERS.filter((a) => !a.verified);
+console.log(`  ${ok('Run against a live agent:')} ${proven.map((a) => a.name).join(', ')}`);
+console.log(`  ${dim('Built to the vendor\'s published hook spec and tested against payloads')}`);
+console.log(`  ${dim('copied from it, but never yet run against the real thing:')}`);
+console.log(`  ${dim('  ' + claimed.map((a) => a.name).join(', '))}`);
+console.log('');
+console.log(dim('  If you use one of those, the useful thing you can do is try it and say'));
+console.log(dim('  what broke: github.com/anujpatel06/nearly/issues'));
+console.log('');
+console.log(dim('  nearly --agent=cursor    turn one on for this repo'));
+console.log(dim('  nearly --agent=all       turn on every one of them'));
+console.log('');

package/scripts/attach.mjs

@@ -6,8 +6,10 @@
 //
 // One command, once per repo. It installs everything and works out the rest:
 //
-//   · Claude Code hooks, so every session in this repo is gated and recorded
-//     whether you start it in a terminal, in VS Code, or in JetBrains
+//   · hooks for every coding agent this repo is driven by, so sessions are
+//     gated and recorded whether you start them in a terminal, in VS Code or in
+//     JetBrains. Claude Code always; Cursor, Antigravity, Copilot, Codex, Gemini
+//     and Windsurf when the repo shows signs of them, or on --agent=
 //   · a git pre-push hook, so the record is offered when the work leaves your
 //     machine
 //   · where the records are published, read from the Nearly's own remote
@@ -20,7 +22,9 @@ import { readFileSync, writeFileSync, mkdirSync, existsSync, realpathSync } from
 import { join, resolve, dirname, basename } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { execFileSync, spawnSync } from 'node:child_process';
-import { dataRoot } from '../server/paths.mjs';
+import { dataRoot, paths } from '../server/paths.mjs';
+import { choose, installed as agentsOnMachine } from './detect.mjs';
+import { ADAPTERS } from '../server/adapters.mjs';
 
 const root = resolve(join(dirname(fileURLToPath(import.meta.url)), '..'));
 const HOOK = join(root, 'scripts', 'hook.mjs');
@@ -78,7 +82,7 @@ const viaNpx = /[\\/]_npx[\\/]/.test(root);
 function installGlobally() {
   if (!viaNpx || onPath() || argv.includes('--no-install') || process.env.NEARLY_NO_INSTALL === '1') return false;
   process.stdout.write(dim(`  Installing nearly so upgrades reach you… `));
-  const r = spawnSync('npm', ['install', '-g', `nearly-cli@${pkgVersion()}`, '--silent', '--no-fund', '--no-audit'],
+  const r = spawnSync(NPM, ['install', '-g', `nearly-cli@${pkgVersion()}`, '--silent', '--no-fund', '--no-audit'],
     { encoding: 'utf8', timeout: 180_000 });
   if (r.status === 0 && onPath()) { console.log('done'); return true; }
   console.log(dim('skipped'));
@@ -92,7 +96,9 @@ const hookCmd = (ev) => installed
   : fromPackage
     ? `npx -y nearly-cli@${pkgVersion()} hook ${ev}`
     : `node ${JSON.stringify(HOOK)} ${ev}`;
-const updateNote = installed
+// A function, not a value: the install below changes the answer, and computing
+// it early told a fresh install it was pinned when it was not.
+const updateNote = () => installed
   ? 'upgrades reach this repo automatically'
   : fromPackage
     ? `pinned to v${pkgVersion()} — run nearly again here after upgrading`
@@ -105,6 +111,9 @@ const nameIdx = argv.indexOf('--name');
 const name = (nameIdx !== -1 ? argv[nameIdx + 1] : basename(repo))
   .replace(/[^a-z0-9-]/gi, '-').toLowerCase().slice(0, 24) || 'repo';
 
+// npm is a .cmd shim on Windows and Node will not run one through spawn unless
+// it is named exactly. Without this, installing and upgrading both fail there.
+const NPM = process.platform === 'win32' ? 'npm.cmd' : 'npm';
 const dim = (s) => `\x1b[2m${s}\x1b[0m`;
 const bold = (s) => `\x1b[1m${s}\x1b[0m`;
 const ok = (s) => `\x1b[32m${s}\x1b[0m`;
@@ -120,43 +129,45 @@ if (!existsSync(join(repo, '.git'))) {
 if (!off && installGlobally()) installed = onPath();
 
 // ---------------------------------------------------------------------------
-// Claude Code hooks
+// Agent hooks
 // ---------------------------------------------------------------------------
-const dir = join(repo, '.claude');
-const file = join(dir, 'settings.local.json');
-mkdirSync(dir, { recursive: true });
-
-let settings = {};
-if (existsSync(file)) {
-  try { settings = JSON.parse(readFileSync(file, 'utf8')); }
-  catch (e) { console.error(`Could not read ${file}: ${e.message}`); process.exit(1); }
-}
-settings.hooks = settings.hooks || {};
-
-// Recognise our own entries by the script they run, so this is safe to re-run
-// and leaves anyone else's hooks alone.
-const ours = (m) => (m?.hooks || []).some((h) =>
-  /nearly/.test(String(h.command || '')) || String(h.command || '').includes(HOOK) ||
-  String(h.url || '').includes(`:${PORT}/hooks/`));
-for (const ev of Object.keys(settings.hooks)) {
-  settings.hooks[ev] = (settings.hooks[ev] || []).filter((m) => !ours(m));
-  if (!settings.hooks[ev].length) delete settings.hooks[ev];
+// Turning off removes every adapter, not just the ones this repo still shows
+// signs of, so nothing is left behind pointing at a command that will not run.
+const { chosen, unknown } = off ? { chosen: ADAPTERS, unknown: [] } : choose(repo, argv);
+if (unknown.length) {
+  console.error(`Unknown agent: ${unknown.join(', ')}`);
+  console.error(`Known: ${ADAPTERS.map((a) => a.id).join(', ')}`);
+  process.exit(1);
 }
 
-if (!off) {
-  const entry = (ev, timeout) => ({
-    hooks: [{ type: 'command', command: `${hookCmd(ev)} ${name}`, timeout }],
-  });
-  const add = (event, ev, timeout) => { settings.hooks[event] = [...(settings.hooks[event] || []), entry(ev, timeout)]; };
-  add('SessionStart', 'session-start', 20);
-  add('UserPromptSubmit', 'prompt', 20);
-  add('PreToolUse', 'pre-tool', 600);   // long enough to hold while a human decides
-  add('PostToolUse', 'post-tool', 20);
-  add('Stop', 'stop', 30);
-  add('SessionEnd', 'session-end', 120);
+const wired = [];
+const notes = [];
+for (const a of chosen) {
+  const cmdFor = (ev) => `${hookCmd(ev)} ${name}` + (a.id === 'claude-code' ? '' : ` --adapter=${a.id}`);
+  try {
+    const r = off ? a.uninstall({ repo }) : a.install({ repo, cmdFor, name });
+    if (r?.error) { notes.push(`${a.name}: ${r.error}`); continue; }
+    if (off ? r?.removed : r?.file) wired.push({ ...a, file: r.file });
+    if (r?.note) notes.push(`${a.name}: ${r.note}`);
+  } catch (e) {
+    // One harness's config being unwritable must not cost you the others.
+    notes.push(`${a.name}: ${e.message}`);
+  }
 }
-if (!Object.keys(settings.hooks).length) delete settings.hooks;
-writeFileSync(file, JSON.stringify(settings, null, 2) + '\n');
+
+// Remember this repo, so the dashboard can offer it before anything has run in
+// it. A list of paths and nothing else: it is a convenience, and it is rebuilt
+// by simply turning Nearly on again.
+try {
+  const f = paths.repos();
+  let list = [];
+  try { list = JSON.parse(readFileSync(f, 'utf8')); } catch { /* first one */ }
+  // Prune as we go: a repo that has been moved or deleted is noise in a list
+  // whose only job is to offer you somewhere to start.
+  list = list.filter((r) => r !== repo && existsSync(join(r, '.git')));
+  if (!off) list.unshift(repo);
+  writeFileSync(f, JSON.stringify(list.slice(0, 50), null, 2) + '\n');
+} catch { /* the dashboard still works without it */ }
 
 // ---------------------------------------------------------------------------
 // git pre-push hook
@@ -208,7 +219,9 @@ if (base && !off) {
 console.log('');
 if (off) {
   console.log(`${bold('Nearly off')} for ${dim(repo)}`);
-  console.log('  Claude Code hooks removed');
+  console.log(wired.length
+    ? `  hooks removed: ${wired.map((a) => a.name).join(', ')}`
+    : '  no agent hooks of ours were installed');
   console.log(push.status === 0 ? '  pre-push hook removed' : dim('  pre-push hook was not ours, left alone'));
   console.log('');
   process.exit(0);
@@ -216,8 +229,11 @@ if (off) {
 
 console.log(`${ok('✓')} ${bold('Nearly is on')} for ${bold(name)}  ${dim(repo)}`);
 console.log('');
-console.log(`  ${ok('·')} every Claude Code session here is gated and recorded`);
-console.log(`  ${ok('·')} ${dim(updateNote)}`);
+for (const a of wired) {
+  const how = a.verified ? dim(`(${a.verified})`) : dim('(built to their published hook spec, not yet run against a live agent)');
+  console.log(`  ${ok('·')} ${a.name} sessions here are gated and recorded ${how}`);
+}
+console.log(`  ${ok('·')} ${dim(updateNote())}`);
 console.log(`  ${ok('·')} ${push.status === 0 ? 'the record is offered when you push' : dim('pre-push hook skipped: ' + (push.stderr || '').trim().split('\n')[0])}`);
 if (base) {
   console.log(`  ${ok('·')} records publish to ${base}`);
@@ -228,6 +244,18 @@ if (base) {
   console.log(`    ${dim('to link them from a pull request, host that folder anywhere and:')}`);
   console.log(`    ${dim('NEARLY_URL_BASE=https://your-host/records nearly')}`);
 }
+for (const n of notes) console.log(`  ${dim('·')} ${dim(n)}`);
+
+// An agent you have on this machine but have not used here is worth a word, and
+// nothing more: having it installed is no reason to write files into this repo.
+const elsewhere = agentsOnMachine().filter((i) => !wired.some((w) => w.id === i.id));
+if (elsewhere.length) {
+  console.log('');
+  console.log(dim(`  Also installed here: ${elsewhere.map((e) => e.name).join(', ')}.`));
+  console.log(dim(`  Nothing in this repo suggests you use them for it, so they were left alone:`));
+  console.log(dim(`  nearly --agent=${elsewhere[0].id} turns one on.`));
+}
+
 console.log('');
 console.log(`  Now just work. Requests that need you appear at ${bold(`http://127.0.0.1:${PORT}`)}`);
 console.log(dim('  Nothing to leave running. Turn it off again with --off.'));

package/scripts/detect.mjs

@@ -0,0 +1,75 @@
+// Which coding agents is this repo actually driven by?
+//
+// The IDE is not the question. Claude Code inside VS Code or a JetBrains IDE is
+// still Claude Code, reading the same settings file, so those need nothing. What
+// matters is the harness making the tool calls, because that is what exposes the
+// hook Nearly attaches to.
+//
+// This exists so nobody has to know that. You run one command; it finds what you
+// use here and turns the gate on for each of them.
+
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { execFileSync } from 'node:child_process';
+import { ADAPTERS, byId } from '../server/adapters.mjs';
+
+// Signals beyond each adapter's own config file: the files a harness leaves in a
+// repo whether or not anybody has configured hooks in it.
+const MARKS = {
+  'claude-code': ['.claude', 'CLAUDE.md', '.claude/settings.json'],
+  cursor: ['.cursor', '.cursorrules', '.cursor/rules'],
+  antigravity: ['.agents', '.antigravity'],
+  copilot: ['.github/copilot-instructions.md', '.github/hooks'],
+  codex: ['.codex', 'AGENTS.md'],
+  gemini: ['.gemini'],
+  windsurf: ['.windsurf', '.windsurfrules'],
+};
+
+const CLIS = {
+  'claude-code': ['claude'], cursor: ['cursor-agent'], antigravity: ['agy'],
+  copilot: ['copilot'], codex: ['codex'], gemini: ['gemini'], windsurf: ['windsurf'],
+};
+
+function onPath(cmd) {
+  try {
+    execFileSync(process.platform === 'win32' ? 'where' : 'which', [cmd],
+      { stdio: ['ignore', 'ignore', 'ignore'] });
+    return true;
+  } catch { return false; }
+}
+
+// A config file in the repo is evidence about this repo. A CLI on PATH is only
+// evidence about the machine, so it is reported separately and never acted on:
+// having Gemini installed is not a reason to write files into someone's project.
+export function detect(repo) {
+  const found = [];
+  for (const a of ADAPTERS) {
+    const marks = [a.config, ...(MARKS[a.id] || [])];
+    const inRepo = marks.some((m) => existsSync(join(repo, m)));
+    if (inRepo) found.push({ id: a.id, name: a.name, why: 'configured in this repo' });
+  }
+  return found;
+}
+
+export function installed() {
+  return ADAPTERS
+    .filter((a) => (CLIS[a.id] || []).some(onPath))
+    .map((a) => ({ id: a.id, name: a.name, why: 'installed on this machine' }));
+}
+
+// What attach should turn on: everything this repo shows signs of, and Claude
+// Code either way, since it is the one that has been run end to end.
+//
+//   --agent=cursor,gemini   exactly these
+//   --agent=all             every adapter there is
+export function choose(repo, argv = []) {
+  const flag = argv.find((a) => a.startsWith('--agent='));
+  if (flag) {
+    const want = flag.slice('--agent='.length).split(',').map((s) => s.trim()).filter(Boolean);
+    if (want.includes('all')) return { chosen: ADAPTERS, unknown: [] };
+    const chosen = want.map(byId).filter(Boolean);
+    return { chosen, unknown: want.filter((w) => !byId(w)) };
+  }
+  const ids = new Set(['claude-code', ...detect(repo).map((d) => d.id)]);
+  return { chosen: ADAPTERS.filter((a) => ids.has(a.id)), unknown: [] };
+}

package/scripts/hook.mjs

@@ -1,7 +1,12 @@
 #!/usr/bin/env node
-// One Claude Code hook event, forwarded to the Nearly.
+// One agent hook event, forwarded to the Nearly.
 //
-//   node scripts/hook.mjs <event> <repo-name>
+//   node scripts/hook.mjs <event> <repo-name> [--adapter=<id>]
+//
+// <event> is always one of Nearly's own names (pre-tool, stop, ...) because
+// attach picks it when it writes the hook. --adapter names whose dialect is
+// arriving on stdin; without one, Claude Code's is assumed and the payload is
+// forwarded untouched, which keeps the oldest path the simplest one.
 //
 // Claude Code writes the event as JSON on stdin and reads our answer from
 // stdout. We sit in between so the server does not have to be running before
@@ -20,15 +25,22 @@
 import { spawn } from 'node:child_process';
 import { join, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { byId } from '../server/adapters.mjs';
 
 const HOST = '127.0.0.1';
 const PORT = Number(process.env.NEARLY_PORT || 47653);
 const BASE = `http://${HOST}:${PORT}`;
 const root = join(dirname(fileURLToPath(import.meta.url)), '..');
 
-const [, , event, name = 'repo'] = process.argv;
+const args = process.argv.slice(2);
+const flag = args.find((a) => a.startsWith('--adapter='));
+const positional = args.filter((a) => !a.startsWith('--'));
+const [event, name = 'repo'] = positional;
 if (!event) process.exit(0);
 
+// An unknown id is a typo in a config file, not a reason to wedge the agent.
+const adapter = flag ? byId(flag.slice('--adapter='.length)) : null;
+
 const body = await new Promise((r) => {
   let s = '';
   process.stdin.setEncoding('utf8');
@@ -65,14 +77,36 @@ if (!(await up()) && !(await start())) process.exit(0);   // fail open, silently
 // stall the agent.
 const budget = event === 'pre-tool' ? 600_000 : 15_000;
 
+// Translate on the way in. A payload we cannot parse is forwarded as it came,
+// so a harness that changes its shape degrades to Claude Code's rather than to
+// nothing.
+let payload = body || '{}';
+if (adapter && adapter.normalize) {
+  try { payload = JSON.stringify(adapter.normalize(event, JSON.parse(body || '{}'))); }
+  catch { /* keep the original */ }
+}
+
 try {
   const res = await fetch(`${BASE}/hooks/${event}?attach=${encodeURIComponent(name)}`, {
     method: 'POST',
     headers: { 'content-type': 'application/json' },
-    body: body || '{}',
+    body: payload,
     signal: AbortSignal.timeout(budget),
   });
   const text = await res.text();
+
+  // ...and on the way out. Rendering is what makes a deny actually land: half of
+  // these harnesses would read Claude Code's answer as no answer at all, and an
+  // unread deny is a gate that reports success while allowing everything.
+  if (adapter && adapter.render) {
+    let answer = {};
+    try { answer = JSON.parse(text || '{}'); } catch { /* treat as no answer */ }
+    const out = adapter.render(event, answer);
+    if (out.stderr) process.stderr.write(out.stderr);
+    if (out.stdout) process.stdout.write(out.stdout);
+    process.exit(out.exit || 0);
+  }
+
   if (text && text !== '{}') process.stdout.write(text);
 } catch { /* fail open */ }
 

package/scripts/update-check.mjs

@@ -24,6 +24,9 @@ import { spawnSync, execFileSync } from 'node:child_process';
 const root = join(dirname(fileURLToPath(import.meta.url)), '..');
 const DAY = 24 * 60 * 60 * 1000;
 
+// npm is a .cmd shim on Windows and Node will not run one through spawn unless
+// it is named exactly. Without this, installing and upgrading both fail there.
+const NPM = process.platform === 'win32' ? 'npm.cmd' : 'npm';
 const dim = (s) => `\x1b[2m${s}\x1b[0m`;
 const bold = (s) => `\x1b[1m${s}\x1b[0m`;
 
@@ -100,7 +103,7 @@ export function applyUpdate(u) {
   }
 
   process.stdout.write(dim(`  Updating Nearly ${u.from} → ${u.to}… `));
-  const r = spawnSync('npm', ['install', '-g', `${u.name}@${u.to}`, '--silent', '--no-fund', '--no-audit'],
+  const r = spawnSync(NPM, ['install', '-g', `${u.name}@${u.to}`, '--silent', '--no-fund', '--no-audit'],
     { encoding: 'utf8', timeout: 120_000 });
 
   if (r.status === 0) {