@raymondchins/agentmap 0.1.0 → 0.2.1

package/NOTICE

@@ -0,0 +1,24 @@
+agentmap — Credits & attribution
+================================
+
+agentmap is copyright 2026 Raymond Surya Chin and contributors,
+licensed under the MIT License (see LICENSE).
+
+-------------------------------------------------------------------------------
+Algorithm credit
+-------------------------------------------------------------------------------
+
+agentmap's repo-map ranking — personalized PageRank importance scoring and the
+identifier-graph symbol ranking — is an independent reimplementation, in
+JavaScript, of the approach introduced by Aider's repo map
+(https://github.com/Aider-AI/aider) by Paul Gauthier and contributors.
+
+No Aider source code is copied or included here: PageRank is a public, textbook
+algorithm, agentmap implements it from scratch (a dependency-free power
+iteration in agentmap.mjs), and Aider itself relies on the networkx library
+rather than hand-written ranking code. This NOTICE is a courtesy credit to the
+project that pioneered applying that ranking approach to a coding-agent repo
+map — not a statement of derivative authorship.
+
+Aider is licensed under the Apache License, Version 2.0
+(http://www.apache.org/licenses/LICENSE-2.0).

package/README.md

@@ -1,19 +1,24 @@
+<p align="center">
+  <img src="assets/hero.png" alt="agentmap — ~98% token savings to understand a codebase (up to 99.9% per task)" width="100%">
+</p>
+
 # agentmap
 
-**The repo map your coding agent is _forced_ to use.**
+**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 — 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.
+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.
 
-<!-- badges (placeholder — wire up once published) -->
 [![npm](https://img.shields.io/npm/v/@raymondchins/agentmap)](https://www.npmjs.com/package/@raymondchins/agentmap)
-[![CI](https://img.shields.io/badge/CI-pending-lightgrey)](#)
+[![CI](https://github.com/raymondchins/agentmap/actions/workflows/ci.yml/badge.svg)](https://github.com/raymondchins/agentmap/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/License-MIT-green)](./LICENSE)
 [![node](https://img.shields.io/badge/node-%3E%3D18-brightgreen)](#)
 
-> One file, one dependency (`ts-morph`). No vector DB, no embedding API, no server.
+> One file, one runtime dependency (`ts-morph`, which bundles the TypeScript compiler — ~10 MB installed). No vector DB, no embedding API, no server.
 > `npx @raymondchins/agentmap --any <query>` and you have a ranked answer.
 
 ---
@@ -53,10 +58,10 @@ npx @raymondchins/agentmap --any <query>
 …or run it directly from a checkout:
 
 ```bash
-node repomap.mjs --any <query>
+node agentmap.mjs --any <query>
 ```
 
-The first run builds and caches the map to `.claude/repomap.json` (add it to
+The first run builds and caches the map to `.claude/agentmap.json` (add it to
 `.gitignore`). Subsequent runs serve the cache when the tree is clean and `HEAD` is
 unchanged, and silently rebuild from disk when there are uncommitted `.ts/.tsx/.js/...`
 edits — so queries always reflect your in-flight work.
@@ -64,8 +69,8 @@ edits — so queries always reflect your in-flight work.
 Run with no flag to build + print a one-line summary:
 
 ```
-$ node repomap.mjs
-repomap: 154 files | 4 features | top hub: lib/utils.ts (deg 52, pr 0.105171)
+$ node agentmap.mjs
+agentmap: 154 files | 4 features | top hub: lib/utils.ts (deg 52, pr 0.105171)
 ```
 
 ---
@@ -91,7 +96,7 @@ graph never indexes still resolve instead of coming up empty.
 **Symbol hit** (query resolved to a symbol → full block):
 
 ```
-$ node repomap.mjs --any cn
+$ node agentmap.mjs --any cn
 [structure] 1 symbol, 0 feature match for "cn"
   lib/utils.ts → cn (FunctionDeclaration)
 ```
@@ -99,7 +104,7 @@ $ node repomap.mjs --any cn
 **Ambiguous file hit** (query matched multiple files → narrow it):
 
 ```
-$ node repomap.mjs --any utils
+$ node agentmap.mjs --any utils
 [structure] "utils" matched 3 files — narrow it:
   lib/utils.ts
   lib/db/utils.ts
@@ -109,7 +114,7 @@ $ node repomap.mjs --any utils
 **Content fallback** (no file/symbol/feature match → live git-grep):
 
 ```
-$ node repomap.mjs --any streamText
+$ node agentmap.mjs --any streamText
 [content] 13 lines:
 app/(chat)/api/chat/route.ts:8:  streamText,
 app/(chat)/api/chat/route.ts:194:        const result = streamText({
@@ -124,7 +129,7 @@ artifacts/sheet/server.ts:11:    const { fullStream } = streamText({
 
 ## Commands
 
-Every snippet below is **verbatim output** from running agentmap against the public
+Every snippet below is **representative output** (long lists trimmed) from running agentmap against the public
 154-file Next.js repo [vercel/ai-chatbot](https://github.com/vercel/ai-chatbot) (sha 2becdb4).
 
 ### `--any <q>` — the router (file → symbol → feature → live content)
@@ -138,7 +143,7 @@ Find every exported symbol whose name contains the query. Use it before writing
 or component to check what already exists.
 
 ```
-$ node repomap.mjs --find Message
+$ node agentmap.mjs --find Message
 find "Message": 55 match
   hooks/use-messages.tsx → useMessages (FunctionDeclaration)
   lib/errors.ts → getMessageByErrorCode (FunctionDeclaration)
@@ -159,7 +164,7 @@ relevance list (personalized PageRank on the bidirectional import graph) — the
 related to the target, transitively, not just its direct importers.
 
 ```
-$ node repomap.mjs --relates lib/db/schema.ts
+$ node agentmap.mjs --relates lib/db/schema.ts
 relates: lib/db/schema.ts  (pr 0.073744)
 exports (14): user(VariableDeclaration), User(TypeAliasDeclaration), chat(VariableDeclaration), Chat(TypeAliasDeclaration), message(VariableDeclaration), DBMessage(TypeAliasDeclaration), …
 imports (0): —
@@ -181,7 +186,7 @@ Resolves a Next.js `app/`-router feature to its file set, plus the external file
 depend on it.
 
 ```
-$ node repomap.mjs --feature api
+$ node agentmap.mjs --feature api
 feature "api": 11 files
   app/(chat)/api/chat/route.ts
   app/(chat)/api/chat/schema.ts
@@ -200,7 +205,7 @@ external dependents (0): —
 ### `--features` — list features by size
 
 ```
-$ node repomap.mjs --features
+$ node agentmap.mjs --features
 features (4):
   api (11 files)
   login (1 files)
@@ -214,8 +219,8 @@ The files that matter most, ranked by PageRank importance (raw dependent degree
 alongside).
 
 ```
-$ node repomap.mjs --hubs
-repomap: 154 files (sha 2becdb4)
+$ node agentmap.mjs --hubs
+agentmap: 154 files (sha 2becdb4)
 hubs (PageRank importance):
   lib/utils.ts (deg 52, pr 0.105171)
   lib/db/schema.ts (deg 21, pr 0.073744)
@@ -233,7 +238,7 @@ The most important individual symbols across the repo, ranked by the identifier
 (defaults to 30).
 
 ```
-$ node repomap.mjs --symbols 10
+$ node agentmap.mjs --symbols 10
 top 10 ranked symbols (Aider-style):
   0.109902  lib/utils.ts → cn (FunctionDeclaration)
   0.036013  lib/types.ts → ChatMessage (TypeAliasDeclaration)
@@ -254,8 +259,8 @@ that fits a token budget. Default budget is 8192 (1024 with `--focus`). `--focus
 personalizes the ranking toward a file you're working on.
 
 ```
-$ node repomap.mjs --map --tokens 400
-# repomap (154 files, sha 2becdb4) — focus: global, budget ~400 tok
+$ node agentmap.mjs --map --tokens 400
+# agentmap (154 files, sha 2becdb4) — focus: global, budget ~400 tok
 
 lib/utils.ts:
   cn (FunctionDeclaration)
@@ -287,8 +292,8 @@ lib/db/schema.ts:
 Focused on a working file — the ranking re-centers on what `lib/db/queries.ts` actually touches:
 
 ```
-$ node repomap.mjs --map --focus lib/db/queries.ts --tokens 350
-# repomap (154 files, sha 2becdb4) — focus: lib/db/queries.ts, budget ~350 tok
+$ node agentmap.mjs --map --focus lib/db/queries.ts --tokens 350
+# agentmap (154 files, sha 2becdb4) — focus: lib/db/queries.ts, budget ~350 tok
 
 lib/utils.ts:
   cn (FunctionDeclaration)
@@ -320,13 +325,25 @@ lib/errors.ts:
 ### `--print` — full map as JSON
 
 Dumps the cached map (`hubs`, `features`, `rankedSymbols`, `files`) as one JSON object —
-for piping into other tools.
+for piping into other tools. Also includes a top-level `fileCount`.
 
 ```
-$ node repomap.mjs --print | jq '.hubs[0]'
+$ node agentmap.mjs --print | jq '.hubs[0]'
 "lib/utils.ts (deg 52, pr 0.105171)"
 ```
 
+### Global flags
+
+| Flag | Description |
+|------|-------------|
+| `--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. |
+| `--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)
@@ -337,22 +354,32 @@ to query the map before it serial-greps.
 
 ### 1. Auto-refresh on commit
 
-[`hooks/post-commit`](./hooks/post-commit) rebuilds `.claude/repomap.json` after each
+[`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 `repomap.mjs`, then `scripts/repomap.mjs`, then
-the installed `agentmap` binary, then `npx @raymondchins/agentmap`.
+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/repomap-nudge.mjs`](./hooks/repomap-nudge.mjs) is a **non-blocking** `PreToolUse(Grep)`
+[`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
@@ -367,7 +394,7 @@ Wire it up in `.claude/settings.json`:
       {
         "matcher": "Grep",
         "hooks": [
-          { "type": "command", "command": "node ./hooks/repomap-nudge.mjs" }
+          { "type": "command", "command": "node ./hooks/agentmap-nudge.mjs" }
         ]
       }
     ]
@@ -385,7 +412,8 @@ agent is steered to it the moment it reaches for a dependency-shaped grep.
 Honesty first — this is deliberately a small, sharp tool, not a universal code-graph.
 
 - **TS/JS only, by design.** Built on `ts-morph`. No Python, Go, Rust, etc. If your repo
-  isn't TypeScript/JavaScript, use a tree-sitter-based tool instead.
+  isn't TypeScript/JavaScript, use a tree-sitter-based tool instead. Support for other
+  languages is a possible future direction.
 - **File-level import graph, not a full reference graph.** Edges come from static
   `import` / re-export declarations and the named symbols crossing them. It does **not**
   do call-site or full reference resolution — `--relates` tells you which files import a
@@ -407,19 +435,19 @@ Honesty first — this is deliberately a small, sharp tool, not a universal code
 
 ## Benchmark
 
-Against the public **154-file Next.js repo (vercel/ai-chatbot, sha 2becdb4)**:
+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%** |
 
-- **70.3% fewer tokens across 3 scenarios (5598 → 1664 tokens)**:
-  - **A. Understand file deps** (`lib/utils.ts`): baseline 583 tok → agentmap 517 tok (11.3% saved)
-  - **B. Find symbol** (`ChatMessage`): baseline 1950 tok → agentmap 20 tok (99% saved)
-  - **C. Repo overview** (tree + 3 hub files): baseline 3065 tok → agentmap 1127 tok (63.2% saved)
-- Cold build (parse + PageRank + symbol graph): **~1.2s**. Warm cached query (`--hubs`,
-  clean tree): **~0.2s**.
+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**.
 
-Caveat: these numbers measure context efficiency (tokens sent to the model per task), **not**
-end-to-end retrieval accuracy — there's no "did the agent fix the bug faster" eval yet.
+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, commands, and caveats: **[`./benchmark/RESULTS.md`](./benchmark/RESULTS.md)**.
+Full methodology, per-repo tables, and all caveats: **[`./benchmark/RESULTS.md`](./benchmark/RESULTS.md)**.
 
 ---
 
@@ -431,8 +459,8 @@ Issues and PRs welcome. High-value directions:
 - A real tokenizer behind the `--map` budget.
 - Hardening feature detection for non-`app/`-router layouts.
 
-Keep the dependency footprint minimal — `ts-morph` is the only runtime dep, and that's a
-feature.
+Keep the dependency footprint minimal — `ts-morph` is the only runtime dependency (it bundles
+the TypeScript compiler, ~10 MB installed), and keeping it that way is a feature.
 
 ## License