Skip to content

Commit 86c8034

Browse files
raymondchinsraymondchins
committed
docs(readme): lead with the agent-loop + benchmark, push command reference down
Reorder only (no content change): the differentiator (agent-loop wiring) and the proof (benchmark) now sit directly under the comparison table, so the page reads hook → why-different → how-it-wins → quickstart. The ~270-line --any router + command reference moves below the fold for readers who are already sold.
1 parent 17640c4 commit 86c8034

1 file changed

Lines changed: 82 additions & 82 deletions

File tree

‎README.md‎

Lines changed: 82 additions & 82 deletions
Original file line numberDiff line numberDiff line change
@@ -47,6 +47,88 @@ and it's a **file-level import graph**, not a full call-site/reference resolver
4747

4848
---
4949

50+
## The agent loop (the actual point)
51+
52+
A repo map only helps if the agent uses it. agentmap ships two hooks (in [`./hooks/`](./hooks/))
53+
that close the loop: the map refreshes itself after every commit, and the agent gets nudged
54+
to query the map before it serial-greps.
55+
56+
### 1. Auto-refresh on commit
57+
58+
[`hooks/post-commit`](./hooks/post-commit) rebuilds `.claude/agentmap.json` after each
59+
commit, detached + silenced so it never slows the commit. It skips during
60+
rebase/merge/cherry-pick and no-ops if Node is missing.
61+
62+
The hooks ship inside the npm package. The simplest setup:
63+
64+
```bash
65+
npx @raymondchins/agentmap --install-hooks
66+
```
67+
68+
This copies `hooks/post-commit` into `.git/hooks/`, sets it executable, ensures
69+
`.claude/agentmap.json` is in `.gitignore`, and **auto-wires the `PreToolUse` nudge
70+
hook into `.claude/settings.json`** (merge-safe + idempotent) so map enforcement is
71+
on by default — no manual paste. Manual alternative for just the post-commit hook:
72+
73+
```bash
74+
# from your repo root
75+
cp hooks/post-commit .git/hooks/post-commit
76+
chmod +x .git/hooks/post-commit
77+
```
78+
79+
The hook auto-locates the builder: a local `agentmap.mjs`, then `scripts/agentmap.mjs`, then
80+
the installed `agentmap` binary, then `npx --no-install @raymondchins/agentmap`.
81+
82+
### 2. Force the agent to use it — `PreToolUse` hook
83+
84+
[`hooks/agentmap-nudge.mjs`](./hooks/agentmap-nudge.mjs) is a **non-blocking** `PreToolUse(Grep)`
85+
hook for Claude Code. When a `Grep` looks like a dependency / who-imports / component-usage /
86+
reuse search, it injects a reminder steering the agent to `agentmap --any` first. It never
87+
denies the grep, and stays silent for raw-string / Tailwind-class / lowercase-HTML-tag
88+
sweeps — so it's high-signal, not nagging.
89+
90+
`--install-hooks` writes this into `.claude/settings.json` for you (merge-safe — it
91+
preserves existing settings and won't duplicate on re-run). For reference, or to wire
92+
it by hand:
93+
94+
```json
95+
{
96+
"hooks": {
97+
"PreToolUse": [
98+
{
99+
"matcher": "Grep",
100+
"hooks": [
101+
{ "type": "command", "command": "node ./hooks/agentmap-nudge.mjs" }
102+
]
103+
}
104+
]
105+
}
106+
}
107+
```
108+
109+
That's the "forced to use it" in the tagline: the map stays current on its own, and the
110+
agent is steered to it the moment it reaches for a dependency-shaped grep.
111+
112+
---
113+
114+
## Benchmark
115+
116+
Measured across **7 agent tasks on 3 real public repos** — reproducible with `node benchmark/bench.mjs <repo>`:
117+
118+
| Repo | Files | Tokens saved |
119+
|------|------:|-------------:|
120+
| [vercel/ai-chatbot](https://github.com/vercel/ai-chatbot) | 154 | **98.3%** |
121+
| [colinhacks/zod](https://github.com/colinhacks/zod) | 367 | **99.2%** |
122+
| [shadcn-ui/taxonomy](https://github.com/shadcn-ui/taxonomy) | 125 | **96.0%** |
123+
124+
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**.
125+
126+
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.
127+
128+
Full methodology, per-repo tables, and all caveats: **[`./benchmark/RESULTS.md`](./benchmark/RESULTS.md)**.
129+
130+
---
131+
50132
## Quickstart
51133

52134
No install needed:
@@ -346,70 +428,6 @@ $ node agentmap.mjs --print | jq '.hubs[0]'
346428

347429
---
348430

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-
413431
## Scope & limitations
414432

415433
Honesty first — this is deliberately a small, sharp tool, not a universal code-graph.
@@ -436,24 +454,6 @@ Honesty first — this is deliberately a small, sharp tool, not a universal code
436454

437455
---
438456

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-
457457
## Contributing
458458

459459
Issues and PRs welcome. High-value directions:

0 commit comments

Comments
 (0)