@raymondchins/agentmap 0.2.2 → 0.2.3
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +130 -95
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -6,12 +6,13 @@
|
|
|
6
6
|
|
|
7
7
|
**The repo map your coding agent is _forced_ to use — ~98% fewer tokens to understand your TS/JS codebase.**
|
|
8
8
|
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
9
|
+
Your AI coding agent re-learns your codebase every session — opening files and grepping to find
|
|
10
|
+
what connects to what, burning tokens before it writes a line. agentmap gives it a **queryable,
|
|
11
|
+
ranked code-relationship map for TypeScript/JavaScript repos** instead — a `ts-morph` import/symbol
|
|
12
|
+
graph ranked by personalized PageRank. Ask it to *"add a field"* or *"fix the login bug"* and it
|
|
13
|
+
finds the right files, their imports, and what already exists in
|
|
14
|
+
**~98% fewer tokens on average** (up to **99.9% per task**) — kept current by a post-commit
|
|
15
|
+
auto-refresh and actually used via a `PreToolUse(Grep)` hook.
|
|
15
16
|
|
|
16
17
|
[](https://www.npmjs.com/package/@raymondchins/agentmap)
|
|
17
18
|
[](https://github.com/raymondchins/agentmap/actions/workflows/ci.yml)
|
|
@@ -23,13 +24,61 @@ published.
|
|
|
23
24
|
|
|
24
25
|
---
|
|
25
26
|
|
|
27
|
+
## Benchmark
|
|
28
|
+
|
|
29
|
+
Every task you hand a coding agent starts with the same hidden step — *find the relevant code*.
|
|
30
|
+
Here's the token cost of that step, **reading raw files vs querying agentmap**, on a real 154-file
|
|
31
|
+
Next.js app ([vercel/ai-chatbot](https://github.com/vercel/ai-chatbot)). Every figure is captured
|
|
32
|
+
tool output (`node benchmark/bench.mjs <repo>` at the pinned sha):
|
|
33
|
+
|
|
34
|
+
<table width="100%">
|
|
35
|
+
<thead>
|
|
36
|
+
<tr>
|
|
37
|
+
<th align="left">The question the agent has to answer first</th>
|
|
38
|
+
<th align="right">Reading files</th>
|
|
39
|
+
<th align="right">With agentmap</th>
|
|
40
|
+
<th align="right">Saved</th>
|
|
41
|
+
</tr>
|
|
42
|
+
</thead>
|
|
43
|
+
<tbody>
|
|
44
|
+
<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>
|
|
45
|
+
<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>
|
|
46
|
+
<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>
|
|
47
|
+
<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>
|
|
48
|
+
<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>
|
|
49
|
+
<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>
|
|
50
|
+
<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>
|
|
51
|
+
<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>
|
|
52
|
+
</tbody>
|
|
53
|
+
</table>
|
|
54
|
+
|
|
55
|
+
<sub>Context tokens the agent burns to answer each question — token est = chars/4, applied to both sides.</sub>
|
|
56
|
+
|
|
57
|
+
That's the agent reaching the same answer on **58× fewer tokens** overall — and the pattern holds
|
|
58
|
+
across [zod](https://github.com/colinhacks/zod) (367 files, **99.2%**) and
|
|
59
|
+
[taxonomy](https://github.com/shadcn-ui/taxonomy) (125 files, **96.0%**), peaking at **646× fewer**
|
|
60
|
+
on a single whole-repo map. Reproducible at pinned shas; full per-scenario tables in
|
|
61
|
+
**[`./benchmark/RESULTS.md`](./benchmark/RESULTS.md)**.
|
|
62
|
+
|
|
63
|
+
**Speed:** a cold build (parse + PageRank + symbol graph) takes **~1.2s**; a warm cached query
|
|
64
|
+
returns in **~0.1s** (the lazy-loaded path added in 0.2.2) — the agent has a ranked answer back
|
|
65
|
+
before it would have finished opening the first handful of files.
|
|
66
|
+
|
|
67
|
+
Honest notes: the win scales with the work — the small rows above (63%, 11%) are the floor, and a
|
|
68
|
+
*trivial single-file* lookup can even cost **more** than `cat`+`grep` (taxonomy's file-import task
|
|
69
|
+
hit −313%; we leave it in). Numbers measure **context-token volume**, not answer quality or wall-clock.
|
|
70
|
+
|
|
71
|
+
---
|
|
72
|
+
|
|
26
73
|
## Why it's different
|
|
27
74
|
|
|
28
|
-
Most "repo context" tools are
|
|
29
|
-
prompt and
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
75
|
+
Most "repo context" tools are a photocopy: they dump your repository (or a slice of it) into
|
|
76
|
+
the prompt once and walk away. The copy goes stale the moment you edit a file, and nothing
|
|
77
|
+
makes the agent actually read it.
|
|
78
|
+
|
|
79
|
+
agentmap is the opposite — a **queryable, ranked, self-refreshing** map the agent interrogates
|
|
80
|
+
flag-by-flag, that **rebuilds itself on every commit**, and that a `PreToolUse` hook steers the
|
|
81
|
+
agent toward *before* it falls back to serial grep.
|
|
33
82
|
|
|
34
83
|
| | **agentmap** | Aider repo map | RepoMapper | Repomix | code2prompt |
|
|
35
84
|
| --- | --- | --- | --- | --- | --- |
|
|
@@ -47,6 +96,73 @@ and it's a **file-level import graph**, not a full call-site/reference resolver
|
|
|
47
96
|
|
|
48
97
|
---
|
|
49
98
|
|
|
99
|
+
## The agent loop (the actual point)
|
|
100
|
+
|
|
101
|
+
Here's the quiet failure of every other repo-map tool: it builds a beautiful map, and then the
|
|
102
|
+
agent forgets it exists and greps anyway. A map the agent doesn't open is just dead weight.
|
|
103
|
+
|
|
104
|
+
agentmap closes that loop. Two hooks (in [`./hooks/`](./hooks/)) do the work: the map
|
|
105
|
+
**refreshes itself after every commit**, and the agent gets **nudged to query it before it
|
|
106
|
+
serial-greps**. You wire it once — then it stays current on its own, and stays used.
|
|
107
|
+
|
|
108
|
+
### 1. Auto-refresh on commit
|
|
109
|
+
|
|
110
|
+
[`hooks/post-commit`](./hooks/post-commit) rebuilds `.claude/agentmap.json` after each
|
|
111
|
+
commit, detached + silenced so it never slows the commit. It skips during
|
|
112
|
+
rebase/merge/cherry-pick and no-ops if Node is missing.
|
|
113
|
+
|
|
114
|
+
The hooks ship inside the npm package. The simplest setup:
|
|
115
|
+
|
|
116
|
+
```bash
|
|
117
|
+
npx @raymondchins/agentmap --install-hooks
|
|
118
|
+
```
|
|
119
|
+
|
|
120
|
+
This copies `hooks/post-commit` into `.git/hooks/`, sets it executable, ensures
|
|
121
|
+
`.claude/agentmap.json` is in `.gitignore`, and **auto-wires the `PreToolUse` nudge
|
|
122
|
+
hook into `.claude/settings.json`** (merge-safe + idempotent) so map enforcement is
|
|
123
|
+
on by default — no manual paste. Manual alternative for just the post-commit hook:
|
|
124
|
+
|
|
125
|
+
```bash
|
|
126
|
+
# from your repo root
|
|
127
|
+
cp hooks/post-commit .git/hooks/post-commit
|
|
128
|
+
chmod +x .git/hooks/post-commit
|
|
129
|
+
```
|
|
130
|
+
|
|
131
|
+
The hook auto-locates the builder: a local `agentmap.mjs`, then `scripts/agentmap.mjs`, then
|
|
132
|
+
the installed `agentmap` binary, then `npx --no-install @raymondchins/agentmap`.
|
|
133
|
+
|
|
134
|
+
### 2. Force the agent to use it — `PreToolUse` hook
|
|
135
|
+
|
|
136
|
+
[`hooks/agentmap-nudge.mjs`](./hooks/agentmap-nudge.mjs) is a **non-blocking** `PreToolUse(Grep)`
|
|
137
|
+
hook for Claude Code. When a `Grep` looks like a dependency / who-imports / component-usage /
|
|
138
|
+
reuse search, it injects a reminder steering the agent to `agentmap --any` first. It never
|
|
139
|
+
denies the grep, and stays silent for raw-string / Tailwind-class / lowercase-HTML-tag
|
|
140
|
+
sweeps — so it's high-signal, not nagging.
|
|
141
|
+
|
|
142
|
+
`--install-hooks` writes this into `.claude/settings.json` for you (merge-safe — it
|
|
143
|
+
preserves existing settings and won't duplicate on re-run). For reference, or to wire
|
|
144
|
+
it by hand:
|
|
145
|
+
|
|
146
|
+
```json
|
|
147
|
+
{
|
|
148
|
+
"hooks": {
|
|
149
|
+
"PreToolUse": [
|
|
150
|
+
{
|
|
151
|
+
"matcher": "Grep",
|
|
152
|
+
"hooks": [
|
|
153
|
+
{ "type": "command", "command": "node ./hooks/agentmap-nudge.mjs" }
|
|
154
|
+
]
|
|
155
|
+
}
|
|
156
|
+
]
|
|
157
|
+
}
|
|
158
|
+
}
|
|
159
|
+
```
|
|
160
|
+
|
|
161
|
+
That's the "forced to use it" in the tagline: the map stays current on its own, and the
|
|
162
|
+
agent is steered to it the moment it reaches for a dependency-shaped grep.
|
|
163
|
+
|
|
164
|
+
---
|
|
165
|
+
|
|
50
166
|
## Quickstart
|
|
51
167
|
|
|
52
168
|
No install needed:
|
|
@@ -77,8 +193,9 @@ agentmap: 154 files | 4 features | top hub: lib/utils.ts (deg 52, pr 0.105171)
|
|
|
77
193
|
|
|
78
194
|
## The `--any` router
|
|
79
195
|
|
|
80
|
-
|
|
81
|
-
|
|
196
|
+
Don't want to learn eight flags? You don't have to. Throw anything at `--any` — a filename, a
|
|
197
|
+
function, a feature, even a raw string — and it figures out what you meant, returning the first
|
|
198
|
+
layer that hits:
|
|
82
199
|
|
|
83
200
|
```
|
|
84
201
|
--any <query>
|
|
@@ -346,70 +463,6 @@ $ node agentmap.mjs --print | jq '.hubs[0]'
|
|
|
346
463
|
|
|
347
464
|
---
|
|
348
465
|
|
|
349
|
-
## The agent loop (the actual point)
|
|
350
|
-
|
|
351
|
-
A repo map only helps if the agent uses it. agentmap ships two hooks (in [`./hooks/`](./hooks/))
|
|
352
|
-
that close the loop: the map refreshes itself after every commit, and the agent gets nudged
|
|
353
|
-
to query the map before it serial-greps.
|
|
354
|
-
|
|
355
|
-
### 1. Auto-refresh on commit
|
|
356
|
-
|
|
357
|
-
[`hooks/post-commit`](./hooks/post-commit) rebuilds `.claude/agentmap.json` after each
|
|
358
|
-
commit, detached + silenced so it never slows the commit. It skips during
|
|
359
|
-
rebase/merge/cherry-pick and no-ops if Node is missing.
|
|
360
|
-
|
|
361
|
-
The hooks ship inside the npm package. The simplest setup:
|
|
362
|
-
|
|
363
|
-
```bash
|
|
364
|
-
npx @raymondchins/agentmap --install-hooks
|
|
365
|
-
```
|
|
366
|
-
|
|
367
|
-
This copies `hooks/post-commit` into `.git/hooks/`, sets it executable, ensures
|
|
368
|
-
`.claude/agentmap.json` is in `.gitignore`, and **auto-wires the `PreToolUse` nudge
|
|
369
|
-
hook into `.claude/settings.json`** (merge-safe + idempotent) so map enforcement is
|
|
370
|
-
on by default — no manual paste. Manual alternative for just the post-commit hook:
|
|
371
|
-
|
|
372
|
-
```bash
|
|
373
|
-
# from your repo root
|
|
374
|
-
cp hooks/post-commit .git/hooks/post-commit
|
|
375
|
-
chmod +x .git/hooks/post-commit
|
|
376
|
-
```
|
|
377
|
-
|
|
378
|
-
The hook auto-locates the builder: a local `agentmap.mjs`, then `scripts/agentmap.mjs`, then
|
|
379
|
-
the installed `agentmap` binary, then `npx --no-install @raymondchins/agentmap`.
|
|
380
|
-
|
|
381
|
-
### 2. Force the agent to use it — `PreToolUse` hook
|
|
382
|
-
|
|
383
|
-
[`hooks/agentmap-nudge.mjs`](./hooks/agentmap-nudge.mjs) is a **non-blocking** `PreToolUse(Grep)`
|
|
384
|
-
hook for Claude Code. When a `Grep` looks like a dependency / who-imports / component-usage /
|
|
385
|
-
reuse search, it injects a reminder steering the agent to `agentmap --any` first. It never
|
|
386
|
-
denies the grep, and stays silent for raw-string / Tailwind-class / lowercase-HTML-tag
|
|
387
|
-
sweeps — so it's high-signal, not nagging.
|
|
388
|
-
|
|
389
|
-
`--install-hooks` writes this into `.claude/settings.json` for you (merge-safe — it
|
|
390
|
-
preserves existing settings and won't duplicate on re-run). For reference, or to wire
|
|
391
|
-
it by hand:
|
|
392
|
-
|
|
393
|
-
```json
|
|
394
|
-
{
|
|
395
|
-
"hooks": {
|
|
396
|
-
"PreToolUse": [
|
|
397
|
-
{
|
|
398
|
-
"matcher": "Grep",
|
|
399
|
-
"hooks": [
|
|
400
|
-
{ "type": "command", "command": "node ./hooks/agentmap-nudge.mjs" }
|
|
401
|
-
]
|
|
402
|
-
}
|
|
403
|
-
]
|
|
404
|
-
}
|
|
405
|
-
}
|
|
406
|
-
```
|
|
407
|
-
|
|
408
|
-
That's the "forced to use it" in the tagline: the map stays current on its own, and the
|
|
409
|
-
agent is steered to it the moment it reaches for a dependency-shaped grep.
|
|
410
|
-
|
|
411
|
-
---
|
|
412
|
-
|
|
413
466
|
## Scope & limitations
|
|
414
467
|
|
|
415
468
|
Honesty first — this is deliberately a small, sharp tool, not a universal code-graph.
|
|
@@ -436,24 +489,6 @@ Honesty first — this is deliberately a small, sharp tool, not a universal code
|
|
|
436
489
|
|
|
437
490
|
---
|
|
438
491
|
|
|
439
|
-
## Benchmark
|
|
440
|
-
|
|
441
|
-
Measured across **7 agent tasks on 3 real public repos** — reproducible with `node benchmark/bench.mjs <repo>`:
|
|
442
|
-
|
|
443
|
-
| Repo | Files | Tokens saved |
|
|
444
|
-
|------|------:|-------------:|
|
|
445
|
-
| [vercel/ai-chatbot](https://github.com/vercel/ai-chatbot) | 154 | **98.3%** |
|
|
446
|
-
| [colinhacks/zod](https://github.com/colinhacks/zod) | 367 | **99.2%** |
|
|
447
|
-
| [shadcn-ui/taxonomy](https://github.com/shadcn-ui/taxonomy) | 125 | **96.0%** |
|
|
448
|
-
|
|
449
|
-
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**.
|
|
450
|
-
|
|
451
|
-
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.
|
|
452
|
-
|
|
453
|
-
Full methodology, per-repo tables, and all caveats: **[`./benchmark/RESULTS.md`](./benchmark/RESULTS.md)**.
|
|
454
|
-
|
|
455
|
-
---
|
|
456
|
-
|
|
457
492
|
## Contributing
|
|
458
493
|
|
|
459
494
|
Issues and PRs welcome. High-value directions:
|