@raymondchins/agentmap 0.2.1 → 0.2.3

package/README.md

@@ -6,12 +6,13 @@
 
 **The repo map your coding agent is _forced_ to use — ~98% fewer tokens to understand your TS/JS codebase.**
 
-A queryable, ranked code-relationship map for TypeScript/JavaScript repos that answers
-"understand the codebase" questions in **~98% fewer tokens on average** (up to **99.9%
-per task**) vs reading raw files. Personalized PageRank importance, Aider-style symbol
-ranking, a token-budgeted digest, and a single `--any` router (file → symbol → feature →
-live git-grep) — wired straight into the agent loop so it actually gets used, not just
-published.
+Your AI coding agent re-learns your codebase every session — opening files and grepping to find
+what connects to what, burning tokens before it writes a line. agentmap gives it a **queryable,
+ranked code-relationship map for TypeScript/JavaScript repos** instead — a `ts-morph` import/symbol
+graph ranked by personalized PageRank. Ask it to *"add a field"* or *"fix the login bug"* and it
+finds the right files, their imports, and what already exists in
+**~98% fewer tokens on average** (up to **99.9% per task**) — kept current by a post-commit
+auto-refresh and actually used via a `PreToolUse(Grep)` hook.
 
 [![npm](https://img.shields.io/npm/v/@raymondchins/agentmap)](https://www.npmjs.com/package/@raymondchins/agentmap)
 [![CI](https://github.com/raymondchins/agentmap/actions/workflows/ci.yml/badge.svg)](https://github.com/raymondchins/agentmap/actions/workflows/ci.yml)
@@ -23,13 +24,61 @@ published.
 
 ---
 
+## Benchmark
+
+Every task you hand a coding agent starts with the same hidden step — *find the relevant code*.
+Here's the token cost of that step, **reading raw files vs querying agentmap**, on a real 154-file
+Next.js app ([vercel/ai-chatbot](https://github.com/vercel/ai-chatbot)). Every figure is captured
+tool output (`node benchmark/bench.mjs <repo>` at the pinned sha):
+
+<table width="100%">
+<thead>
+<tr>
+<th align="left">The question the agent has to answer first</th>
+<th align="right">Reading files</th>
+<th align="right">With agentmap</th>
+<th align="right">Saved</th>
+</tr>
+</thead>
+<tbody>
+<tr><td align="left">Where is this symbol defined?</td><td align="right">1,950</td><td align="right">20</td><td align="right">99%</td></tr>
+<tr><td align="left">Does a helper for this already exist? <i>(reuse)</i></td><td align="right">14,740</td><td align="right">19</td><td align="right">99.9%</td></tr>
+<tr><td align="left">What breaks if I change this file? <i>(blast radius)</i></td><td align="right">81,038</td><td align="right">616</td><td align="right">99.2%</td></tr>
+<tr><td align="left">What files make up this feature?</td><td align="right">6,121</td><td align="right">1,025</td><td align="right">83.3%</td></tr>
+<tr><td align="left">Give me a repo overview</td><td align="right">3,065</td><td align="right">1,127</td><td align="right">63.2%</td></tr>
+<tr><td align="left">Load the whole repo into context</td><td align="right">150,281</td><td align="right">1,127</td><td align="right">99.3%</td></tr>
+<tr><td align="left">What does this one file import?</td><td align="right">583</td><td align="right">517</td><td align="right">11.3%</td></tr>
+<tr><td align="left"><b>All 7 tasks combined</b></td><td align="right"><b>257,778</b></td><td align="right"><b>4,451</b></td><td align="right"><b>98.3%</b></td></tr>
+</tbody>
+</table>
+
+<sub>Context tokens the agent burns to answer each question — token est = chars/4, applied to both sides.</sub>
+
+That's the agent reaching the same answer on **58× fewer tokens** overall — and the pattern holds
+across [zod](https://github.com/colinhacks/zod) (367 files, **99.2%**) and
+[taxonomy](https://github.com/shadcn-ui/taxonomy) (125 files, **96.0%**), peaking at **646× fewer**
+on a single whole-repo map. Reproducible at pinned shas; full per-scenario tables in
+**[`./benchmark/RESULTS.md`](./benchmark/RESULTS.md)**.
+
+**Speed:** a cold build (parse + PageRank + symbol graph) takes **~1.2s**; a warm cached query
+returns in **~0.1s** (the lazy-loaded path added in 0.2.2) — the agent has a ranked answer back
+before it would have finished opening the first handful of files.
+
+Honest notes: the win scales with the work — the small rows above (63%, 11%) are the floor, and a
+*trivial single-file* lookup can even cost **more** than `cat`+`grep` (taxonomy's file-import task
+hit −313%; we leave it in). Numbers measure **context-token volume**, not answer quality or wall-clock.
+
+---
+
 ## Why it's different
 
-Most "repo context" tools are one-shot: they pack the repository (or a slice of it) into a
-prompt and stop there. agentmap is a **queryable, ranked, and self-refreshing** map that an
-agent can interrogate flag-by-flag — and, crucially, is **wired into the agent loop** via a
-post-commit auto-refresh and a `PreToolUse` hook that nudges the agent to use the map
-*before* it falls back to serial grep.
+Most "repo context" tools are a photocopy: they dump your repository (or a slice of it) into
+the prompt once and walk away. The copy goes stale the moment you edit a file, and nothing
+makes the agent actually read it.
+
+agentmap is the opposite — a **queryable, ranked, self-refreshing** map the agent interrogates
+flag-by-flag, that **rebuilds itself on every commit**, and that a `PreToolUse` hook steers the
+agent toward *before* it falls back to serial grep.
 
 | | **agentmap** | Aider repo map | RepoMapper | Repomix | code2prompt |
 | --- | --- | --- | --- | --- | --- |
@@ -47,6 +96,73 @@ and it's a **file-level import graph**, not a full call-site/reference resolver
 
 ---
 
+## The agent loop (the actual point)
+
+Here's the quiet failure of every other repo-map tool: it builds a beautiful map, and then the
+agent forgets it exists and greps anyway. A map the agent doesn't open is just dead weight.
+
+agentmap closes that loop. Two hooks (in [`./hooks/`](./hooks/)) do the work: the map
+**refreshes itself after every commit**, and the agent gets **nudged to query it before it
+serial-greps**. You wire it once — then it stays current on its own, and stays used.
+
+### 1. Auto-refresh on commit
+
+[`hooks/post-commit`](./hooks/post-commit) rebuilds `.claude/agentmap.json` after each
+commit, detached + silenced so it never slows the commit. It skips during
+rebase/merge/cherry-pick and no-ops if Node is missing.
+
+The hooks ship inside the npm package. The simplest setup:
+
+```bash
+npx @raymondchins/agentmap --install-hooks
+```
+
+This copies `hooks/post-commit` into `.git/hooks/`, sets it executable, ensures
+`.claude/agentmap.json` is in `.gitignore`, and **auto-wires the `PreToolUse` nudge
+hook into `.claude/settings.json`** (merge-safe + idempotent) so map enforcement is
+on by default — no manual paste. Manual alternative for just the post-commit hook:
+
+```bash
+# from your repo root
+cp hooks/post-commit .git/hooks/post-commit
+chmod +x .git/hooks/post-commit
+```
+
+The hook auto-locates the builder: a local `agentmap.mjs`, then `scripts/agentmap.mjs`, then
+the installed `agentmap` binary, then `npx --no-install @raymondchins/agentmap`.
+
+### 2. Force the agent to use it — `PreToolUse` hook
+
+[`hooks/agentmap-nudge.mjs`](./hooks/agentmap-nudge.mjs) is a **non-blocking** `PreToolUse(Grep)`
+hook for Claude Code. When a `Grep` looks like a dependency / who-imports / component-usage /
+reuse search, it injects a reminder steering the agent to `agentmap --any` first. It never
+denies the grep, and stays silent for raw-string / Tailwind-class / lowercase-HTML-tag
+sweeps — so it's high-signal, not nagging.
+
+`--install-hooks` writes this into `.claude/settings.json` for you (merge-safe — it
+preserves existing settings and won't duplicate on re-run). For reference, or to wire
+it by hand:
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Grep",
+        "hooks": [
+          { "type": "command", "command": "node ./hooks/agentmap-nudge.mjs" }
+        ]
+      }
+    ]
+  }
+}
+```
+
+That's the "forced to use it" in the tagline: the map stays current on its own, and the
+agent is steered to it the moment it reaches for a dependency-shaped grep.
+
+---
+
 ## Quickstart
 
 No install needed:
@@ -77,8 +193,9 @@ agentmap: 154 files | 4 features | top hub: lib/utils.ts (deg 52, pr 0.105171)
 
 ## The `--any` router
 
-One flag, no flag-picking. `--any <query>` resolves your query through a cascade and
-returns the first layer that hits:
+Don't want to learn eight flags? You don't have to. Throw anything at `--any` — a filename, a
+function, a feature, even a raw string — and it figures out what you meant, returning the first
+layer that hits:
 
 ```
 --any <query>
@@ -339,74 +456,13 @@ $ node agentmap.mjs --print | jq '.hubs[0]'
 | `--help` / `-h` | Print a usage block listing every flag and exit 0. |
 | `--version` / `-v` | Print the version from `package.json` and exit 0. |
 | `--json` | **Global modifier.** When present, every command prints exactly one JSON object to stdout (no prose). Shapes vary per command: `--json --hubs` → `{command,fileCount,sha,hubs:[string]}`, `--json --find X` → `{command,query,matches:[{file,name,kind}]}`, `--json --relates X` → `{command,file,pagerank,exports,imports,dependents,related}`, `--json --any X` → `{command,query,kind,…payload}`, etc. Bare `--json` (no query flag) → `{command:"build",fileCount,features,topHub}`. |
-| `--install-hooks` | Copy `hooks/post-commit` into `.git/hooks/` (chmod 0755), ensure `.claude/agentmap.json` is in `.gitignore`, and print the Claude Code `settings.json` `PreToolUse` snippet. Exit 0 on success, stderr + exit 1 on failure. |
+| `--install-hooks` | Copy `hooks/post-commit` into `.git/hooks/` (chmod 0755), ensure `.claude/agentmap.json` is in `.gitignore`, and auto-wire the Claude Code `PreToolUse(Grep)` nudge into `.claude/settings.json` (merge-safe + idempotent). Exit 0 on success, stderr + exit 1 on failure. |
 | `--mcp` | Start agentmap as a **stdio MCP server** so non-Claude-Code agents (Cursor, Cline, any MCP client) can call every flag as a first-class tool. |
 
 **Exit-code contract:** `0` = success / match / help / version; `1` = query returned zero results (`--any`, `--find`, `--relates`, `--feature` with no match); `2` = usage error (missing required arg, unknown flag). Any token starting with `-` that matches no known flag prints an error to stderr and exits 2.
 
 ---
 
-## The agent loop (the actual point)
-
-A repo map only helps if the agent uses it. agentmap ships two hooks (in [`./hooks/`](./hooks/))
-that close the loop: the map refreshes itself after every commit, and the agent gets nudged
-to query the map before it serial-greps.
-
-### 1. Auto-refresh on commit
-
-[`hooks/post-commit`](./hooks/post-commit) rebuilds `.claude/agentmap.json` after each
-commit, detached + silenced so it never slows the commit. It skips during
-rebase/merge/cherry-pick and no-ops if Node is missing.
-
-The hooks ship inside the npm package. The simplest setup:
-
-```bash
-npx @raymondchins/agentmap --install-hooks
-```
-
-This copies `hooks/post-commit` into `.git/hooks/`, sets it executable, ensures
-`.claude/agentmap.json` is in `.gitignore`, and prints the `.claude/settings.json`
-snippet for the `PreToolUse` nudge hook (below). Manual alternative:
-
-```bash
-# from your repo root
-cp hooks/post-commit .git/hooks/post-commit
-chmod +x .git/hooks/post-commit
-```
-
-The hook auto-locates the builder: a local `agentmap.mjs`, then `scripts/agentmap.mjs`, then
-the installed `agentmap` binary, then `npx --no-install @raymondchins/agentmap`.
-
-### 2. Force the agent to use it — `PreToolUse` hook
-
-[`hooks/agentmap-nudge.mjs`](./hooks/agentmap-nudge.mjs) is a **non-blocking** `PreToolUse(Grep)`
-hook for Claude Code. When a `Grep` looks like a dependency / who-imports / component-usage /
-reuse search, it injects a reminder steering the agent to `agentmap --any` first. It never
-denies the grep, and stays silent for raw-string / Tailwind-class / lowercase-HTML-tag
-sweeps — so it's high-signal, not nagging.
-
-Wire it up in `.claude/settings.json`:
-
-```json
-{
-  "hooks": {
-    "PreToolUse": [
-      {
-        "matcher": "Grep",
-        "hooks": [
-          { "type": "command", "command": "node ./hooks/agentmap-nudge.mjs" }
-        ]
-      }
-    ]
-  }
-}
-```
-
-That's the "forced to use it" in the tagline: the map stays current on its own, and the
-agent is steered to it the moment it reaches for a dependency-shaped grep.
-
----
-
 ## Scope & limitations
 
 Honesty first — this is deliberately a small, sharp tool, not a universal code-graph.
@@ -433,24 +489,6 @@ Honesty first — this is deliberately a small, sharp tool, not a universal code
 
 ---
 
-## Benchmark
-
-Measured across **7 agent tasks on 3 real public repos** — reproducible with `node benchmark/bench.mjs <repo>`:
-
-| Repo | Files | Tokens saved |
-|------|------:|-------------:|
-| [vercel/ai-chatbot](https://github.com/vercel/ai-chatbot) | 154 | **98.3%** |
-| [colinhacks/zod](https://github.com/colinhacks/zod) | 367 | **99.2%** |
-| [shadcn-ui/taxonomy](https://github.com/shadcn-ui/taxonomy) | 125 | **96.0%** |
-
-Per-task peaks (real, across the three repos): **whole-repo map 99.8%**, **reuse-before-rebuild lookup 99.9%**, **blast-radius 99.2%**, **find-symbol 99%**. Cold build (parse + PageRank + symbol graph) **~1.2s**; warm cached query **~0.2s**.
-
-Honest notes: the win scales with repo size — a *trivial single-file* `--any` lookup can actually cost **more** than `cat`+`grep` (taxonomy showed −313% on that one task; we leave it in). Numbers measure **context-token volume**, not end-to-end retrieval accuracy. Token est = `chars / 4`, applied to both sides.
-
-Full methodology, per-repo tables, and all caveats: **[`./benchmark/RESULTS.md`](./benchmark/RESULTS.md)**.
-
----
-
 ## Contributing
 
 Issues and PRs welcome. High-value directions:

package/agentmap.mjs

@@ -13,11 +13,18 @@
 //  Near-zero deps (ts-morph only). Runs in the target repo's cwd.
 //  Algorithm credit: Aider's repo map (Apache-2.0) — github.com/Aider-AI/aider
 // ============================================================================
-import { Project, SyntaxKind } from "ts-morph";
-const CallExpression = SyntaxKind.CallExpression;
 import { writeFileSync, readFileSync, existsSync, mkdirSync, renameSync, readdirSync, statSync, chmodSync } from "node:fs";
 import { execSync, execFileSync } from "node:child_process";
 import { createHash } from "node:crypto";
+import { createRequire } from "node:module";
+
+// Lazy ts-morph: its ~105ms module init only fires on a COLD rebuild. Warm cache
+// queries (the common case) never construct a Project, so they skip the load
+// entirely (~2x faster warm). createRequire keeps it synchronous — no async to
+// thread through build()/makeProject().
+const _require = createRequire(import.meta.url);
+let _tsm = null;
+const tsMorph = () => (_tsm ??= _require("ts-morph"));
 
 const MAP = ".claude/agentmap.json";
 const SCHEMA_VERSION = 2;
@@ -177,6 +184,7 @@ function identMul(ident, defineCount, mentioned) {
 // else (missing / malformed / solution-style references that index 0 files) fall
 // back to broad source globs so the tool degrades gracefully instead of crashing.
 function makeProject() {
+  const { Project } = tsMorph();
   // skipFileDependencyResolution: ~40% faster build, verified identical edge
   // set (we resolve module specifiers explicitly below, never via the implicit
   // dependency graph). allowJs so .js/.jsx are parsed.
@@ -248,6 +256,8 @@ function makeProject() {
 function build() {
   const t0 = Date.now();
   const project = makeProject();
+  const { SyntaxKind } = tsMorph();
+  const CallExpression = SyntaxKind.CallExpression;
   const cwd = process.cwd().replace(/\\/g, "/");
   const rel = (p) => p.replace(cwd + "/", "");
   const files = {}, dependents = {}, features = {};
@@ -534,14 +544,13 @@ function fileBlock(key, f) {
 
 // ---------------------------------------------------------------------------
 // --install-hooks: copy the package post-commit hook into .git/hooks, ensure
-// .claude/agentmap.json is gitignored, and print the Claude Code PreToolUse
-// snippet (mirrors hooks/INSTALL.md). Throws on any failure so the caller can
-// stderr+exit 1. Resolves the package hooks/ dir relative to THIS script so it
-// works whether agentmap is run locally, via npx, or globally installed.
+// .claude/agentmap.json is gitignored, and auto-wire the Claude Code
+// PreToolUse(Grep) nudge into the project's .claude/settings.json so map
+// enforcement is ON by default (no manual copy-paste). Merge-safe + idempotent.
+// Throws on any failure so the caller can stderr+exit 1.
 // ---------------------------------------------------------------------------
 function installHooks() {
   const src = new URL("./hooks/post-commit", import.meta.url);
-  const nudge = new URL("./hooks/agentmap-nudge.mjs", import.meta.url);
   // The package hooks/ dir must ship alongside agentmap.mjs.
   if (!existsSync(src)) throw new Error(`packaged hook not found at ${src.pathname} (is the hooks/ dir present?)`);
 
@@ -565,14 +574,36 @@ function installHooks() {
     writeFileSync(".gitignore", IGNORE_LINE + "\n");
   }
 
-  // Success report + the ready-to-paste PreToolUse snippet (points node at the
-  // installed nudge — use its absolute path so it resolves from any cwd).
+  // Auto-wire the PreToolUse(Grep) enforcement nudge into the PROJECT settings
+  // (.claude/settings.json) so "the agent is forced to use the map" is ON by
+  // default — not a manual paste. Merge-safe + idempotent: preserves any
+  // existing settings/hooks, never duplicates our entry. Uses a project-relative
+  // command so a committed settings.json stays portable across machines.
+  const NUDGE_CMD = "node node_modules/@raymondchins/agentmap/hooks/agentmap-nudge.mjs";
+  const settingsPath = ".claude/settings.json";
+  let settings = {};
+  if (existsSync(settingsPath)) {
+    try { settings = JSON.parse(readFileSync(settingsPath, "utf8")) || {}; }
+    catch { throw new Error(`${settingsPath} is not valid JSON — fix or remove it, then re-run --install-hooks`); }
+  }
+  settings.hooks ??= {};
+  settings.hooks.PreToolUse ??= [];
+  const alreadyWired = settings.hooks.PreToolUse.some(
+    (e) => Array.isArray(e?.hooks) && e.hooks.some((h) => typeof h?.command === "string" && h.command.includes("agentmap-nudge")),
+  );
+  if (!alreadyWired) {
+    settings.hooks.PreToolUse.push({ matcher: "Grep", hooks: [{ type: "command", command: NUDGE_CMD }] });
+    mkdirSync(".claude", { recursive: true });
+    writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + "\n");
+  }
+
+  // Success report.
   console.log(`installed post-commit hook → ${dest}`);
   console.log(ignoredAlready ? `.gitignore already has ${IGNORE_LINE}` : `added ${IGNORE_LINE} to .gitignore`);
-  console.log("\nAdd this to your .claude/settings.json to enable the PreToolUse(Grep) nudge:\n");
-  console.log(JSON.stringify({
-    hooks: { PreToolUse: [{ matcher: "Grep", hooks: [{ type: "command", command: `node ${nudge.pathname}` }] }] },
-  }, null, 2));
+  console.log(alreadyWired
+    ? `${settingsPath} already wires the PreToolUse(Grep) → agentmap nudge — left as-is`
+    : `wired PreToolUse(Grep) → agentmap nudge into ${settingsPath} (map enforcement on by default)`);
+  console.log("\nDone — the map auto-refreshes on commit, and greps are nudged to agentmap first.");
 }
 
 // ---------------------------------------------------------------------------

package/hooks/INSTALL.md

@@ -121,8 +121,10 @@ agentmap --install-hooks
 ```
 
 This copies `hooks/post-commit` to `.git/hooks/post-commit`, chmods it, ensures
-`.claude/agentmap.json` is in `.gitignore`, and prints the Claude Code
-`settings.json` PreToolUse snippet — all in one step.
+`.claude/agentmap.json` is in `.gitignore`, and auto-wires the Claude Code
+`PreToolUse(Grep)` nudge into `.claude/settings.json` (merge-safe — preserves
+existing settings, idempotent on re-run) — enforcement on by default, all in one
+step. No manual paste needed.
 
 **Manual alternative:**
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@raymondchins/agentmap",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "publishConfig": {
     "access": "public"
   },