agentmap

<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 TS/JS-accurate repo map for your coding agent — a compiler-grade `ts-morph` import/symbol graph that answers "where is it / what breaks / does this already exist" in ~98% fewer context tokens.**

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 (the real TypeScript compiler, so aliases, `vite`/`webpack` `resolve.alias`, package.json
`#imports` subpaths, and workspace cross-package imports all resolve) 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 context tokens on average** (up to **~99.9% per task**; figures are chars/4 estimates applied equally to both sides) — kept current by a post-commit
auto-refresh and actually used via a `PreToolUse(Grep)` hook.

> **agentmap's wedge in one line:** it's the **TS/JS-*accurate*** repo map — a real TypeScript-compiler graph, not a tree-sitter approximation — with a published, honest [accuracy eval](./EVAL.md) to back it. That precision is the point; the auto-refresh/nudge wiring below is convenience, not the moat.

[![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)
[![License: MIT](https://img.shields.io/badge/License-MIT-green)](./LICENSE)
[![node](https://img.shields.io/badge/node-%3E%3D18-brightgreen)](#)

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

---

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

> **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 ~95%** of the time (naive grep ~79%) at **~2.6× fewer tokens**, and
identifies a module's dependents at **~100% precision** (grep ~58%). 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), ~57k★) 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