# Agentmap

> Stop your coding agent reading the wrong files. Compiler-grade TS/JS repo map — 100% precision on blast radius vs grep's 60%, measured on public repos. CLI + MCP server, fully local, no vector DB.

- **Type:** MCP server
- **Install:** `agentstack add mcp-raymondchins-agentmap`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [raymondchins](https://agentstack.voostack.com/s/raymondchins)
- **Installs:** 0
- **Category:** [Developer Tools](https://agentstack.voostack.com/c/developer-tools)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [raymondchins](https://github.com/raymondchins)
- **Source:** https://github.com/raymondchins/agentmap

## Install

```sh
agentstack add mcp-raymondchins-agentmap
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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).

```bash
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](https://github.com/colinhacks/zod), [zustand](https://github.com/pmndrs/zustand) and [hono](https://github.com/honojs/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`](https://www.npmjs.com/package/@raymondchins/agentmap)

---

## Quickstart

No install needed:

```bash
npx @raymondchins/agentmap --any 
```

…or run it directly from a checkout:

```bash
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](https://github.com/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](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)**.

> **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](https://github.com/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](https://github.com/colbymchenry/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](https://github.com/colbymchenry/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:

```bash
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:

```bash
# 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):

```json
{
  "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](https://github.com/raymondchins)
- **Source:** [raymondchins/agentmap](https://github.com/raymondchins/agentmap)
- **License:** MIT

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-raymondchins-agentmap
- Seller: https://agentstack.voostack.com/s/raymondchins
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.