Agentmap

agentmap

Stop your coding agent from reading the wrong files.

Ask "what breaks if I change this?" and grep hands back a pile where 40% of the files don't actually depend on it. agentmap answers the same question at 100% precision — measured, on public repos, [reproducibly](./EVAL.md).

npx @raymondchins/agentmap --relates src/lib/auth.ts

Your agent re-learns your codebase every session, grepping to find what connects to what and burning tokens before it writes a line. agentmap gives it a queryable, PageRank-ranked import/symbol map instead — built with ts-morph, the real TypeScript compiler, so it resolves what string matching cannot.

| Question | agentmap | git grep | |---|---|---| | What depends on this file? | 100% precision, 99.2% recall | 59.9% precision | | Where is this symbol defined? | 53.3% top-1, 93.3% top-3 | 32% top-1, 80% top-3 | | Tokens to find a definition | ~2.4× fewer | — |

n=42 dependents / n=75 definitions across zod, zustand and hono at pinned commits. Ground truth is derived at runtime by an independent resolver, not hand-authored. Re-run it yourself: npm run eval. Full method + per-repo numbers: [EVAL.md](./EVAL.md).

Precision is the point: every wrong file your agent opens is context spent being misled. --relates returns the full blast radius, so it costs more tokens than a bare grep -l file list — and that trade is [stated plainly in the eval](./EVAL.md), not hidden.

[](https://www.npmjs.com/package/@raymondchins/agentmap) [](https://github.com/raymondchins/agentmap/actions/workflows/ci.yml) [](./LICENSE) [](#)

> 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 and you have a ranked answer. > > Fully local — no network calls, no telemetry, no data leaves your machine. agentmap > reads your code, writes a cache under .claude/agentmap/, and never phones home (there is > not a single fetch/http call in the source). Your code is never sent anywhere. > > ⚠️ Always install the scoped name: @raymondchins/agentmap. npx agentmap > (unscoped) runs an unrelated package by a different author — this project is > @raymondchins/agentmap, and the scoped name is required in every install and command. > npmjs.com/package/@raymondchins/agentmap

---

Quickstart

No install needed:

npx @raymondchins/agentmap --any 

…or run it directly from a checkout:

node agentmap.mjs --any 

The first run builds and caches the map to .claude/agentmap/map.json (add .claude/agentmap/ 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.

Run with no flag to build + print a one-line summary:

$ node agentmap.mjs
agentmap: 154 files | 4 features | top hub: lib/utils.ts (deg 52, pr 0.105171)

---

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). Every figure is captured tool output (node benchmark/bench.mjs at the pinned sha):

The question the agent has to answer first Reading files With agentmap Saved

Where is this symbol defined?1,9502099% Does a helper for this already exist? (reuse)14,7401999.9% What breaks if I change this file? (blast radius)81,03861699.2% What files make up this feature?6,1211,02583.3% Give me a repo overview3,0651,12763.2% Load the whole repo into context150,2811,12799.3% What does this one file import?58351711.3% All 7 tasks combined257,7784,45198.3%

Context tokens the agent burns to answer each question — token est = chars/4, applied to both sides.

That's the agent reaching the same answer on 58× fewer tokens overall — and the pattern holds across zod (367 files, 99.2%) and 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).

> Methodology note: the 58× overall figure is dominated by the whole-repo-load scenario > (Scenario F — 150 K vs 1 K tokens), which skews the combined ratio sharply upward. Excluding it, > the per-task overall ratio on the same sample repo is approximately 32×. Both numbers are real; > the headline captures the most common agent worst-case (repo-dump on session start), while the > per-task average better represents typical individual queries. RESULTS.md has the full breakdown.

Fewer tokens, but are they the right tokens? Token efficiency is only half the story — a separate [EVAL.md](./EVAL.md) (npm run eval) scores retrieval accuracy against ground truth derived live from real repos (zod, zustand, hono). Headline: agentmap returns the symbol definition in the top 3 93.3% of the time (naive grep 80%) at ~2.4× fewer tokens, and identifies a module's dependents at 100% precision / 99.2% recall (grep 100% recall but 59.9% precision). Fixtures are pinned to exact commits, so those numbers are re-derivable rather than whatever upstream happened to look like the day they were taken. Honest tradeoffs and method in EVAL.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

Many "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 queryable and ranked instead: the agent interrogates it flag-by-flag rather than swallowing a dump.

But the real reason to reach for agentmap is accuracy. It's built on ts-morph — the actual TypeScript compiler — so its import graph resolves the things a text/tree-sitter scanner guesses at: tsconfig/jsconfig paths, vite/vitest/webpack resolve.alias, package.json Node #imports subpaths, and pnpm/npm/yarn workspace cross-package imports. It reports an edgeCoverage map-health signal and warns loudly when a repo's imports mostly don't resolve, so a broken map is never framed as success — and a separate [EVAL.md](./EVAL.md) scores retrieval accuracy against live ground truth. That compiler-grade precision on TS/JS is the wedge.

The self-refreshing side — a post-commit rebuild plus a PreToolUse hook that steers the agent to the map before it serial-greps — is genuinely useful, but it isn't unique: CodeGraph (colbymchenry/codegraph, ~62k★ (2026-07-26)) ships a native OS-event file watcher (FSEvents/inotify) with debounced auto-sync and an installer that auto-configures eight agent CLIs. agentmap's honest edge over the multi-language graph tools is narrower and sharper: TS/JS resolution the others approximate, with a published accuracy eval.

| | agentmap | Aider repo map | RepoMapper | Repomix | code2prompt | | --- | --- | --- | --- | --- | --- | | Ranking algorithm | Personalized PageRank (file + symbol graphs) | PageRank (graph ranking) | Importance heuristics | None (file order) | None (file order) | | Languages | TS/JS + Vue SFC (via ts-morph) | Many (tree-sitter) | Many (tree-sitter) | Language-agnostic (text) | Language-agnostic (text) | | Token-budget output | Yes — --map [--tokens N] ranked digest | Yes (built into Aider's context) | Partial | Yes (size caps) | Yes (templates/caps) | | TS/JS resolution depth | Compiler-grade — tsconfig paths + vite/webpack alias + #imports + workspaces (ts-morph) | Basename/regex heuristics | Basename/regex heuristics | N/A (text) | N/A (text) | | Retrieval-accuracy eval | Yes — published [EVAL.md](./EVAL.md) vs live ground truth | No | No | No | No | | Agent-loop wiring | Yes — post-commit auto-refresh + PreToolUse hook | In-process (Aider only) | No | No | No | | Dependencies | ts-morph only | Python + tree-sitter stack | Python + tree-sitter | Node | Rust binary | | Install | npx @raymondchins/agentmap | pip install aider-chat | pip install | npx/global | cargo/binary |

What that table is not claiming: agentmap is TS/JS-only (the others are multi-language), and it's a file-level import graph, not a full call-site/reference resolver (see [Scope & limitations](#scope--limitations)). The differentiators are narrow and honest: (1) compiler-grade TS/JS resolution (aliases, vite/webpack, #imports, workspaces) with a published accuracy eval, and (2) the --any router. The agent-loop wiring is real and convenient but not unique — CodeGraph and others auto-sync and auto-configure agent CLIs too; we don't claim it as a moat.

---

The agent loop (staying current, staying used)

A common failure of repo-map tools: they build 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.

> This wiring is table stakes, not the moat — CodeGraph > and other tools also auto-sync (via native OS file watchers) and auto-configure agent CLIs. > agentmap ships it because it's genuinely useful; the actual point of agentmap is the > compiler-grade TS/JS accuracy the map is built on.

1. Auto-refresh on commit

[hooks/post-commit](./hooks/post-commit) rebuilds .claude/agentmap/map.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:

npx @raymondchins/agentmap --install-hooks

This copies hooks/post-commit into .git/hooks/, sets it executable, ensures .claude/agentmap/ 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:

# from your repo root
cp hooks/post-commit .git/hooks/post-commit
chmod +x .git/hooks/post-commit

The hook resolves the builder to the installed package — node_modules/.bin/agentmap, a PATH agentmap binary verified to be @raymondchins/agentmap, then npx @raymondchins/agentmap. It never runs a repo-local ./agentmap.mjs unless you opt in with AGENTMAP_HOOK_ALLOW_LOCAL=1 (for developing agentmap itself), so an attacker-planted agentmap.mjs can't execute on your next commit.

2. Force the agent to use it — PreToolUse hook

[hooks/agentmap-nudge.mjs](./hooks/agentmap-nudge.mjs) is a non-blocking hook for Claude Code that covers both the Grep tool and raw Bash text-searchers (grep/rg/egrep/fgrep/ag/ack). When either looks like a dependency / who-imports / component-usage / reuse / where-is-symbol search, it injects a reminder steering the agent to agentmap --any first. It never denies the call, and stays silent for raw-string / Tailwind-class / lowercase-HTML-tag sweeps and for pipe-filtered commands like ps aux | grep node — so it's high-signal, not nagging.

Fires on: import/require/export/from '...' patterns, JSX component tags ( **One thing the plugin can't do: install the git post-commit hook.** Claude Code > plugins can't write into .git/hooks/, so the auto-refresh-on-commit still needs a > one-time npx @raymondchins/agentmap --install-hooks in each repo (it also wires the > nudge into .claude/settings.json`, harmlessly redundant with the plugin's copy). > Without it the map still rebuilds on any dirty query — you just lose the commit-time > refresh.

Onboarding by platform

Enforcement isn't uniform — some CLIs get a live hook that actively steers grep to agentmap, some get an MCP server the agent can call, and some are docs-only (a skill/rule the agent may or may not consult). Honest matrix:

| Platform | Install | Enforcement | Known gaps | |----------|---------|-------------|------------| | Claude Code | /plugin install agentmap@agentmap (or --install-hooks) | live hook — PreToolUse nudge on Grep + Bash searchers | non-blocking (never denies grep); bare-symbol Grep nudge requires the #3 hook fix | | Gemini CLI | --install-skill --platform gemini | live hook — .gemini/settings.json nudge | fires on the AfterTool/systemMessage path (the earlier BeforeTool + additionalContext combo was silently dropped — fixed in #4) | | OpenCode | --install-skill --platform opencode | log-only — .opencode/plugins/agentmap-nudge.js writes to the log, does not inject context | plugin can't steer the model; relies on the AGENTS.md block being read | | Cursor | --install-skill --platform cursor + .cursor/mcp.json (below) | MCP + docs — alwaysApply rule + the MCP server | Cursor's own hooks aren't wired; the rule is advisory | | Codex CLI | --install-skill --platform codex | live gate — .codex/config.toml PreToolUse hook | denies only high-confidence structural greps; allow-fallback for logs/pipes/non-TS-JS; AGENTMAP_CODEX_GATE=0 bypasses; needs a trusted dir + Codex hooks-GA | | Copilot CLI | --install-skill --platform copilot | docs-only — .copilot/skills/ | same as Codex — no live hook yet |

Cursor MCP — copy-paste .cursor/mcp.json (Cursor's --mcp wiring is a documented dead-end otherwise; drop this at your repo root):

{
  "mcpServers": {
    "agentmap": {
      "command": "npx",
      "args": ["-y", "@raymondchins/agentmap", "--mcp"]
    }
  }
}

Then Cursor exposes the 11 query tools (any, find, relates, map, hubs, features, feature, symbols, search, callers, calls). Run agentmap --doctor any time to see what's wired vs missing.

Uninstall

agentmap only writes files into your repo/home — remove them to fully uninstall. agentmap --doctor lists every path it wrote, and every docs merge lives inside an ` (or # agentmap:begin/end) fence, so deleting just that block leaves the rest of your AGENTS.md / GEMINI.md` intact.

| Platform | Remove | |----------|--------| | Claude Code | .claude/skills/agentmap/ + the agentmap PreToolUse block in .claude/settings.json | | Cursor | .cursor/rules/agentmap.mdc + the agentmap entry in .cursor/mcp.json | | Codex | .codex/skills/agentmap/, the # agentmap:begin/end block in .codex/config.toml, .codex/hooks/agentmap-codex-nudge.mjs, and the fenced block in AGENTS.md | | OpenCode | .opencode/skills/agentmap/, .opencode/plugins/agentmap-nudge.js, the AGENTS.md block | | Gemini | `.gemini/skills/a

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: raymondchins
• Source: raymondchins/agentmap
• License: MIT

Install and usage instructions live in the source repository linked above.