<p align="center"> <img src="assets/hero.png" alt="agentmap — 98% fewer tokens for a coding agent to find your code" width="100%"> </p> <p align="center"> <a href="https://www.npmjs.com/package/@raymondchins/agentmap"><img src="https://img.shields.io/npm/v/@raymondchins/agentmap" alt="npm"></a> <a href="https://github.com/raymondchins/agentmap/actions/workflows/ci.yml"><img src="https://github.com/raymondchins/agentmap/actions/workflows/ci.yml/badge.svg" alt="CI"></a> <a href="./LICENSE"><img src="https://img.shields.io/badge/License-MIT-green" alt="License: MIT"></a> <a href="#"><img src="https://img.shields.io/badge/node-%3E%3D20-brightgreen" alt="node >= 20"></a> <a href="#"><img src="https://img.shields.io/badge/runtime%20deps-1-2EE0A8" alt="1 runtime dependency"></a> <a href="#"><img src="https://img.shields.io/badge/network%20calls-0-2EE0A8" alt="zero network calls"></a> </p>

agentmap

Your agent burns most of its context just finding code. This gives it the answer in one line.

npx @raymondchins/agentmap --relates lib/db/schema.ts

relates: lib/db/schema.ts  (pr 0.073744)
dependents (21): lib/types.ts, lib/utils.ts, lib/db/queries.ts,
                 components/chat/message.tsx, app/(chat)/api/chat/route.ts, …

Every file on that list really imports it. grep gets 40% of them wrong.

---

💸 What it saves

Token cost of the hidden first step in every agent task — find the relevant code — on a real 154-file Next.js app (vercel/ai-chatbot, sha 2becdb4):

| The agent needs to know… | Reading files | agentmap | Saved | |---|---:|---:|:---:| | Does a helper for this already exist? | 14,740 | 19 | 99.9% | | Load the whole repo into context | 150,281 | 1,127 | 99.3% | | What breaks if I change this file? | 81,038 | 616 | 99.2% | | Where is this symbol defined? | 1,950 | 20 | 99% | | What files make up this feature? | 6,121 | 1,025 | 83.3% | | Give me a repo overview | 3,065 | 1,127 | 63.2% | | What does this one file import? | 583 | 517 | 11.3% | | All 7 combined | 257,778 | 4,451 | 98.3% |

Holds on zod too (367 files, 99.2%) and taxonomy (125 files, 96.0%). Captured output, pinned shas → benchmark/RESULTS.md

🎯 …and it's still right

Fewer tokens is worthless if they're the wrong ones. Separate eval, ground truth derived live from real repos:

| | agentmap | git grep | |---|:---:|:---:| | What depends on this file? | 100% precision | 59.9% precision | | Where is this defined? (top-1) | 100% | 32% | | Where is this defined? (top-3) | 100% | 80% | | Tokens to find a definition | 1.9× fewer | — |

_{n=42 dependents / n=75 definitions across <a href="https://github.com/colinhacks/zod">zod</a>, <a href="https://github.com/pmndrs/zustand">zustand</a>, <a href="https://github.com/honojs/hono">hono</a>. Re-run: <code>npm run eval</code> · method → <a href="./EVAL.md">EVAL.md</a>}

---

⚡ The five commands

| You want | Run | Saves | |---|---|:---:| | "Do we already have this?" | agentmap --find formatCurrency | 99.9% | | "What breaks if I touch this?" | agentmap --relates lib/auth.ts | 99.2% | | "Where is this defined?" | agentmap --find ChatMessage | 99% | | "Give me the repo, cheap" | agentmap --map --tokens 2000 | 99.3% | | Don't want to pick? | agentmap --any <anything> | — |

--any routes it for you: file → symbol → feature → live content search.

Cold build ~1.2s. Cached query ~0.1s. No server, no vector DB, no API key.

---

🔌 Setup

npx @raymondchins/agentmap --install-hooks   # rebuild on commit + steer the agent to the map
npx @raymondchins/agentmap --install-skill   # Claude Code · Cursor · Codex · Gemini · OpenCode · Copilot

Most repo-map tools stop at building the map. These two hooks are why it stays useful: the map rebuilds itself after every commit, and the agent gets nudged to the map the moment it reaches for a dependency-shaped grep. Claude Code users can get both from the plugin.

100% local. Zero network calls, zero telemetry — not one fetch/http in the source. ⚠️ Install the scoped name; unscoped npx agentmap is someone else's package.

<details> <summary>Where the cache lives, and how it stays fresh</summary> <br>

First run caches to .claude/agentmap/map.json (--install-hooks gitignores it). Later runs serve that cache only on a clean tree at an unchanged HEAD — with uncommitted .ts/.tsx/.js/… edits it silently rebuilds, so you never query a stale snapshot.

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

From a checkout, every command also works as node agentmap.mjs ….

</details>

---

🧠 Why the answers are right

Built on ts-morph — the real TypeScript compiler, not text matching or tree-sitter guessing. It resolves tsconfig path aliases, vite/webpack aliases, #imports subpaths, and monorepo workspaces. Where grep sees a string, agentmap sees the resolved module.

That's also why barrels don't fool it: export * from "./x" looks identical to a real definition to a text search, so your agent edits the re-export and changes nothing. agentmap follows the chain and names the file that actually declares it.

<details> <summary><b>The honest asterisks</b> — read these before quoting a number</summary> <br>

• The win scales with the work. The 63% and 11% rows are the floor. A trivial single-file lookup can cost more than cat + grep — taxonomy's file-import task hit −313%, and it stays in the table.
• The 98.3% headline is carried by its two biggest rows — repo dump (150,281 → 1,127) and blast radius (81,038 → 616). Drop the repo dump and it's 96.9%; drop both and it's 89.8% here, 93.7% pooled across all three repos, and 73.1% on the smallest one. All of those are real — they answer different questions. The headline is the common worst case: an agent dumping the repo at session start.
• --relates returns the full blast radius, so it costs more than a bare grep -l file list. That's why the same command reads as 99.2% saved in the benchmark and more expensive in the eval: the benchmark's baseline is an agent that cats all 65 dependent files, the eval's is a file list nobody reads. Against the list, agentmap trades tokens for precision — 100% vs 59.9%, so ~4 in 10 files on the grep list don't belong. Complete-and-correct over short-and-wrong, but it is a trade → EVAL.md.
• Numbers are context-token volume, not answer quality or wall-clock.
• Token counts are estimates (chars / 4), applied identically to both sides.
• TypeScript/JavaScript only (+ Vue SFC) — see Scope & limitations.

</details>

---

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.

It also reports an edgeCoverage map-health signal and warns loudly when a repo's imports mostly don't resolve, so a broken map is never quietly framed as success.

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 vs live ground truth | No | No | No | No | | Agent-loop wiring | Yes — post-commit auto-refresh + PreToolUse hook | In-process (Aider only) | No | MCP server (no auto-refresh, no nudge) | 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 |

_{Comparison as of <b>2026-07-27</b>, from each project's own docs. These are moving targets — if a cell is out of date, that's a bug: <a href="https://github.com/raymondchins/agentmap/issues">open an issue</a>.}

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). 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/) 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 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: