@raymondchins/agentmap 0.1.0 → 0.2.0
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/LICENSE-APACHE +194 -0
- package/NOTICE +19 -0
- package/README.md +75 -47
- package/agentmap.mjs +894 -0
- package/hooks/INSTALL.md +211 -0
- package/hooks/agentmap-nudge.mjs +90 -0
- package/hooks/post-commit +61 -0
- package/mcp.mjs +206 -0
- package/package.json +12 -6
- package/repomap.mjs +0 -461
package/LICENSE-APACHE
ADDED
|
@@ -0,0 +1,194 @@
|
|
|
1
|
+
Apache License
|
|
2
|
+
Version 2.0, January 2004
|
|
3
|
+
http://www.apache.org/licenses/
|
|
4
|
+
|
|
5
|
+
TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
|
|
6
|
+
|
|
7
|
+
1. Definitions.
|
|
8
|
+
|
|
9
|
+
"License" shall mean the terms and conditions for use, reproduction,
|
|
10
|
+
and distribution as defined by Sections 1 through 9 of this document.
|
|
11
|
+
|
|
12
|
+
"Licensor" shall mean the copyright owner or entity authorized by
|
|
13
|
+
the copyright owner that is granting the License.
|
|
14
|
+
|
|
15
|
+
"Legal Entity" shall mean the union of the acting entity and all
|
|
16
|
+
other entities that control, are controlled by, or are under common
|
|
17
|
+
control with that entity. For the purposes of this definition,
|
|
18
|
+
"control" means (i) the power, direct or indirect, to cause the
|
|
19
|
+
direction or management of such entity, whether by contract or
|
|
20
|
+
otherwise, or (ii) ownership of fifty percent (50%) or more of the
|
|
21
|
+
outstanding shares, or (iii) beneficial ownership of such entity.
|
|
22
|
+
|
|
23
|
+
"You" (or "Your") shall mean an individual or Legal Entity
|
|
24
|
+
exercising permissions granted by this License.
|
|
25
|
+
|
|
26
|
+
"Source" form shall mean the preferred form for making modifications,
|
|
27
|
+
including but not limited to software source code, documentation
|
|
28
|
+
source, and configuration files.
|
|
29
|
+
|
|
30
|
+
"Object" form shall mean any form resulting from mechanical
|
|
31
|
+
transformation or translation of a Source form, including but
|
|
32
|
+
not limited to compiled object code, generated documentation,
|
|
33
|
+
and conversions to other media types.
|
|
34
|
+
|
|
35
|
+
"Work" shall mean the work of authorship made available under
|
|
36
|
+
the License, as indicated by a copyright notice that is included in
|
|
37
|
+
or attached to the work (an example is provided in the Appendix below).
|
|
38
|
+
|
|
39
|
+
"Derivative Works" shall mean any work, whether in Source or Object
|
|
40
|
+
form, that is based on (or derived from) the Work and for which the
|
|
41
|
+
editorial revisions, annotations, elaborations, or other modifications
|
|
42
|
+
represent, as a whole, an original work of authorship. For the purposes
|
|
43
|
+
of this License, Derivative Works shall not include works that remain
|
|
44
|
+
separable from, or merely link (or bind by name) to the interfaces of,
|
|
45
|
+
the Work and Derivative Works thereof.
|
|
46
|
+
|
|
47
|
+
"Contribution" shall mean, as submitted to the Licensor for inclusion
|
|
48
|
+
in the Work by the copyright owner or by an individual or Legal Entity
|
|
49
|
+
authorized to submit on behalf of the copyright owner. For the purposes
|
|
50
|
+
of this definition, "submitted" means any form of electronic, verbal,
|
|
51
|
+
or written communication sent to the Licensor or its representatives,
|
|
52
|
+
including but not limited to communication on electronic mailing lists,
|
|
53
|
+
source code control systems, and issue tracking systems that are managed
|
|
54
|
+
by, or on behalf of, the Licensor for the purpose of discussing and
|
|
55
|
+
improving the Work, but excluding communication that is conspicuously
|
|
56
|
+
marked or designated in writing by the copyright owner as "Not a
|
|
57
|
+
Contribution."
|
|
58
|
+
|
|
59
|
+
"Contributor" shall mean Licensor and any Legal Entity on behalf of
|
|
60
|
+
whom a Contribution has been received by the Licensor and included
|
|
61
|
+
within the Work.
|
|
62
|
+
|
|
63
|
+
2. Grant of Copyright License. Subject to the terms and conditions of
|
|
64
|
+
this License, each Contributor hereby grants to You a perpetual,
|
|
65
|
+
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
|
|
66
|
+
copyright license to reproduce, prepare Derivative Works of,
|
|
67
|
+
publicly display, publicly perform, sublicense, and distribute the
|
|
68
|
+
Work and such Derivative Works in Source or Object form.
|
|
69
|
+
|
|
70
|
+
3. Grant of Patent License. Subject to the terms and conditions of
|
|
71
|
+
this License, each Contributor hereby grants to You a perpetual,
|
|
72
|
+
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
|
|
73
|
+
(except as stated in this section) patent license to make, have made,
|
|
74
|
+
use, offer to sell, sell, import, and otherwise transfer the Work,
|
|
75
|
+
where such license applies only to those patent claims licensable
|
|
76
|
+
by such Contributor that are necessarily infringed by their
|
|
77
|
+
Contribution(s) alone or by the combination of their Contribution(s)
|
|
78
|
+
with the Work to which such Contribution(s) was submitted. If You
|
|
79
|
+
institute patent litigation against any entity (including a cross-claim
|
|
80
|
+
or counterclaim in a lawsuit) alleging that the Work or any
|
|
81
|
+
Contribution embodied within the Work constitutes direct or contributory
|
|
82
|
+
patent infringement, then any patent licenses granted to You under
|
|
83
|
+
this License for that Work shall terminate as of the date such
|
|
84
|
+
litigation is filed.
|
|
85
|
+
|
|
86
|
+
4. Redistribution. You may reproduce and distribute copies of the
|
|
87
|
+
Work or Derivative Works thereof in any medium, with or without
|
|
88
|
+
modifications, and in Source or Object form, provided that You
|
|
89
|
+
meet the following conditions:
|
|
90
|
+
|
|
91
|
+
(a) You must give any other recipients of the Work or Derivative Works
|
|
92
|
+
a copy of this License; and
|
|
93
|
+
|
|
94
|
+
(b) You must cause any modified files to carry prominent notices
|
|
95
|
+
stating that You changed the files; and
|
|
96
|
+
|
|
97
|
+
(c) You must retain, in the Source form of any Derivative Works
|
|
98
|
+
that You distribute, all copyright, patent, trademark, and
|
|
99
|
+
attribution notices from the Source form of the Work,
|
|
100
|
+
excluding those notices that do not pertain to any part of
|
|
101
|
+
the Derivative Works; and
|
|
102
|
+
|
|
103
|
+
(d) If the Work includes a "NOTICE" text file as part of its
|
|
104
|
+
distribution, You must include a readable copy of the attribution
|
|
105
|
+
notices contained within such NOTICE file, in at least one
|
|
106
|
+
of the following places: within a NOTICE text file distributed
|
|
107
|
+
as part of the Derivative Works; within the Source form or
|
|
108
|
+
documentation, if provided along with the Derivative Works; or,
|
|
109
|
+
within a display generated by the Derivative Works, if and
|
|
110
|
+
wherever such third-party notices normally appear. The contents
|
|
111
|
+
of the NOTICE file are for informational purposes only and
|
|
112
|
+
do not modify the License. You may add Your own attribution
|
|
113
|
+
notices within Derivative Works that You distribute, alongside
|
|
114
|
+
or as an addendum to the NOTICE text from the Work, provided
|
|
115
|
+
that such additional attribution notices cannot be construed
|
|
116
|
+
as modifying the License.
|
|
117
|
+
|
|
118
|
+
You may add Your own license statement for Your modifications and
|
|
119
|
+
may provide additional grant of rights to use, reproduce, modify,
|
|
120
|
+
prepare Derivative Works of, convert to other media types, publicly
|
|
121
|
+
display, publicly perform, sublicense, and distribute such modifications
|
|
122
|
+
and Derivative Works as a whole, provided Your use, reproduction,
|
|
123
|
+
and distribution of the Work otherwise complies with the conditions
|
|
124
|
+
stated in this License.
|
|
125
|
+
|
|
126
|
+
5. Submission of Contributions. Unless You explicitly state otherwise,
|
|
127
|
+
any Contribution intentionally submitted for inclusion in the Work
|
|
128
|
+
by You to the Licensor shall be under the terms and conditions of
|
|
129
|
+
this License, without any additional terms or conditions.
|
|
130
|
+
Notwithstanding the above, nothing herein shall supersede or modify
|
|
131
|
+
the terms of any separate license agreement you may have executed
|
|
132
|
+
with Licensor regarding such Contributions.
|
|
133
|
+
|
|
134
|
+
6. Trademarks. This License does not grant permission to use the trade
|
|
135
|
+
names, trademarks, service marks, or product names of the Licensor,
|
|
136
|
+
except as required for reasonable and customary use in describing the
|
|
137
|
+
origin of the Work and reproducing the content of the NOTICE file.
|
|
138
|
+
|
|
139
|
+
7. Disclaimer of Warranty. Unless required by applicable law or
|
|
140
|
+
agreed to in writing, Licensor provides the Work (and each
|
|
141
|
+
Contributor provides its Contributions) on an "AS IS" BASIS,
|
|
142
|
+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
|
|
143
|
+
implied, including, without limitation, any warranties or conditions
|
|
144
|
+
of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
|
|
145
|
+
PARTICULAR PURPOSE. You are solely responsible for determining the
|
|
146
|
+
appropriateness of using or reproducing the Work and assume any
|
|
147
|
+
risks associated with Your exercise of permissions under this License.
|
|
148
|
+
|
|
149
|
+
8. Limitation of Liability. In no event and under no legal theory,
|
|
150
|
+
whether in tort (including negligence), contract, or otherwise,
|
|
151
|
+
unless required by applicable law (such as deliberate and grossly
|
|
152
|
+
negligent acts) or agreed to in writing, shall any Contributor be
|
|
153
|
+
liable to You for damages, including any direct, indirect, special,
|
|
154
|
+
incidental, or exemplary damages of any character arising as a
|
|
155
|
+
result of this License or out of the use or inability to use the
|
|
156
|
+
Work (including but not limited to damages for loss of goodwill,
|
|
157
|
+
work stoppage, computer failure or malfunction, or all other
|
|
158
|
+
commercial damages or losses), even if such Contributor has been
|
|
159
|
+
advised of the possibility of such damages.
|
|
160
|
+
|
|
161
|
+
9. Accepting Warranty or Additional Liability. While redistributing
|
|
162
|
+
the Work or Derivative Works thereof, You may choose to offer,
|
|
163
|
+
and charge a fee for, acceptance of support, warranty, indemnity,
|
|
164
|
+
or other liability obligations and/or rights consistent with this
|
|
165
|
+
License. However, in accepting such obligations, You may offer only
|
|
166
|
+
conditions consistent with this License, provided that You also
|
|
167
|
+
comply with the terms of this License, and, if applicable, offer
|
|
168
|
+
insurance and/or a fee for each obligation of benefit to the
|
|
169
|
+
Derivative Works.
|
|
170
|
+
|
|
171
|
+
END OF TERMS AND CONDITIONS
|
|
172
|
+
|
|
173
|
+
APPENDIX: How to apply the Apache License to your work.
|
|
174
|
+
|
|
175
|
+
To apply the Apache License to your work, attach the following
|
|
176
|
+
boilerplate notice, with the fields enclosed by brackets "[]"
|
|
177
|
+
replaced with your own identifying information. (Don't include
|
|
178
|
+
the brackets!) The text should be enclosed in the appropriate
|
|
179
|
+
comment syntax for the file format in question. It may also be
|
|
180
|
+
printed or read aloud for identification purposes.
|
|
181
|
+
|
|
182
|
+
Copyright [yyyy] [name of copyright owner]
|
|
183
|
+
|
|
184
|
+
Licensed under the Apache License, Version 2.0 (the "License");
|
|
185
|
+
you may not use this file except in compliance with the License.
|
|
186
|
+
You may obtain a copy of the License at
|
|
187
|
+
|
|
188
|
+
http://www.apache.org/licenses/LICENSE-2.0
|
|
189
|
+
|
|
190
|
+
Unless required by applicable law or agreed to in writing, software
|
|
191
|
+
distributed under the License is distributed on an "AS IS" BASIS,
|
|
192
|
+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
193
|
+
See the License for the specific language governing permissions and
|
|
194
|
+
limitations under the License.
|
package/NOTICE
ADDED
|
@@ -0,0 +1,19 @@
|
|
|
1
|
+
agentmap — NOTICE
|
|
2
|
+
=================
|
|
3
|
+
|
|
4
|
+
agentmap is copyright 2026 Raymond Surya Chin and contributors,
|
|
5
|
+
licensed under the MIT License (see LICENSE).
|
|
6
|
+
|
|
7
|
+
-------------------------------------------------------------------------------
|
|
8
|
+
Third-party attribution
|
|
9
|
+
-------------------------------------------------------------------------------
|
|
10
|
+
|
|
11
|
+
The repo-map ranking algorithm in agentmap.mjs — specifically the PageRank-based
|
|
12
|
+
importance scoring and identifier-graph symbol ranking — is ported from Aider
|
|
13
|
+
(https://github.com/Aider-AI/aider) by Paul Gauthier and contributors.
|
|
14
|
+
|
|
15
|
+
Aider is licensed under the Apache License, Version 2.0. The full text of
|
|
16
|
+
that license is in LICENSE-APACHE in this package.
|
|
17
|
+
|
|
18
|
+
You may obtain a copy of the Apache License at:
|
|
19
|
+
http://www.apache.org/licenses/LICENSE-2.0
|
package/README.md
CHANGED
|
@@ -1,19 +1,24 @@
|
|
|
1
|
+
<p align="center">
|
|
2
|
+
<img src="assets/hero.png" alt="agentmap — ~98% token savings to understand a codebase (up to 99.9% per task)" width="100%">
|
|
3
|
+
</p>
|
|
4
|
+
|
|
1
5
|
# agentmap
|
|
2
6
|
|
|
3
|
-
**The repo map your coding agent is _forced_ to use.**
|
|
7
|
+
**The repo map your coding agent is _forced_ to use — ~98% fewer tokens to understand your TS/JS codebase.**
|
|
4
8
|
|
|
5
|
-
A queryable, ranked code-relationship map for TypeScript/JavaScript repos
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
+
A queryable, ranked code-relationship map for TypeScript/JavaScript repos that answers
|
|
10
|
+
"understand the codebase" questions in **~98% fewer tokens on average** (up to **99.9%
|
|
11
|
+
per task**) vs reading raw files. Personalized PageRank importance, Aider-style symbol
|
|
12
|
+
ranking, a token-budgeted digest, and a single `--any` router (file → symbol → feature →
|
|
13
|
+
live git-grep) — wired straight into the agent loop so it actually gets used, not just
|
|
14
|
+
published.
|
|
9
15
|
|
|
10
|
-
<!-- badges (placeholder — wire up once published) -->
|
|
11
16
|
[](https://www.npmjs.com/package/@raymondchins/agentmap)
|
|
12
|
-
[](https://github.com/raymondchins/agentmap/actions/workflows/ci.yml)
|
|
13
18
|
[](./LICENSE)
|
|
14
19
|
[](#)
|
|
15
20
|
|
|
16
|
-
> One file, one dependency (`ts-morph
|
|
21
|
+
> One file, one runtime dependency (`ts-morph`, which bundles the TypeScript compiler — ~10 MB installed). No vector DB, no embedding API, no server.
|
|
17
22
|
> `npx @raymondchins/agentmap --any <query>` and you have a ranked answer.
|
|
18
23
|
|
|
19
24
|
---
|
|
@@ -53,10 +58,10 @@ npx @raymondchins/agentmap --any <query>
|
|
|
53
58
|
…or run it directly from a checkout:
|
|
54
59
|
|
|
55
60
|
```bash
|
|
56
|
-
node
|
|
61
|
+
node agentmap.mjs --any <query>
|
|
57
62
|
```
|
|
58
63
|
|
|
59
|
-
The first run builds and caches the map to `.claude/
|
|
64
|
+
The first run builds and caches the map to `.claude/agentmap.json` (add it to
|
|
60
65
|
`.gitignore`). Subsequent runs serve the cache when the tree is clean and `HEAD` is
|
|
61
66
|
unchanged, and silently rebuild from disk when there are uncommitted `.ts/.tsx/.js/...`
|
|
62
67
|
edits — so queries always reflect your in-flight work.
|
|
@@ -64,8 +69,8 @@ edits — so queries always reflect your in-flight work.
|
|
|
64
69
|
Run with no flag to build + print a one-line summary:
|
|
65
70
|
|
|
66
71
|
```
|
|
67
|
-
$ node
|
|
68
|
-
|
|
72
|
+
$ node agentmap.mjs
|
|
73
|
+
agentmap: 154 files | 4 features | top hub: lib/utils.ts (deg 52, pr 0.105171)
|
|
69
74
|
```
|
|
70
75
|
|
|
71
76
|
---
|
|
@@ -91,7 +96,7 @@ graph never indexes still resolve instead of coming up empty.
|
|
|
91
96
|
**Symbol hit** (query resolved to a symbol → full block):
|
|
92
97
|
|
|
93
98
|
```
|
|
94
|
-
$ node
|
|
99
|
+
$ node agentmap.mjs --any cn
|
|
95
100
|
[structure] 1 symbol, 0 feature match for "cn"
|
|
96
101
|
lib/utils.ts → cn (FunctionDeclaration)
|
|
97
102
|
```
|
|
@@ -99,7 +104,7 @@ $ node repomap.mjs --any cn
|
|
|
99
104
|
**Ambiguous file hit** (query matched multiple files → narrow it):
|
|
100
105
|
|
|
101
106
|
```
|
|
102
|
-
$ node
|
|
107
|
+
$ node agentmap.mjs --any utils
|
|
103
108
|
[structure] "utils" matched 3 files — narrow it:
|
|
104
109
|
lib/utils.ts
|
|
105
110
|
lib/db/utils.ts
|
|
@@ -109,7 +114,7 @@ $ node repomap.mjs --any utils
|
|
|
109
114
|
**Content fallback** (no file/symbol/feature match → live git-grep):
|
|
110
115
|
|
|
111
116
|
```
|
|
112
|
-
$ node
|
|
117
|
+
$ node agentmap.mjs --any streamText
|
|
113
118
|
[content] 13 lines:
|
|
114
119
|
app/(chat)/api/chat/route.ts:8: streamText,
|
|
115
120
|
app/(chat)/api/chat/route.ts:194: const result = streamText({
|
|
@@ -124,7 +129,7 @@ artifacts/sheet/server.ts:11: const { fullStream } = streamText({
|
|
|
124
129
|
|
|
125
130
|
## Commands
|
|
126
131
|
|
|
127
|
-
Every snippet below is **
|
|
132
|
+
Every snippet below is **representative output** (long lists trimmed) from running agentmap against the public
|
|
128
133
|
154-file Next.js repo [vercel/ai-chatbot](https://github.com/vercel/ai-chatbot) (sha 2becdb4).
|
|
129
134
|
|
|
130
135
|
### `--any <q>` — the router (file → symbol → feature → live content)
|
|
@@ -138,7 +143,7 @@ Find every exported symbol whose name contains the query. Use it before writing
|
|
|
138
143
|
or component to check what already exists.
|
|
139
144
|
|
|
140
145
|
```
|
|
141
|
-
$ node
|
|
146
|
+
$ node agentmap.mjs --find Message
|
|
142
147
|
find "Message": 55 match
|
|
143
148
|
hooks/use-messages.tsx → useMessages (FunctionDeclaration)
|
|
144
149
|
lib/errors.ts → getMessageByErrorCode (FunctionDeclaration)
|
|
@@ -159,7 +164,7 @@ relevance list (personalized PageRank on the bidirectional import graph) — the
|
|
|
159
164
|
related to the target, transitively, not just its direct importers.
|
|
160
165
|
|
|
161
166
|
```
|
|
162
|
-
$ node
|
|
167
|
+
$ node agentmap.mjs --relates lib/db/schema.ts
|
|
163
168
|
relates: lib/db/schema.ts (pr 0.073744)
|
|
164
169
|
exports (14): user(VariableDeclaration), User(TypeAliasDeclaration), chat(VariableDeclaration), Chat(TypeAliasDeclaration), message(VariableDeclaration), DBMessage(TypeAliasDeclaration), …
|
|
165
170
|
imports (0): —
|
|
@@ -181,7 +186,7 @@ Resolves a Next.js `app/`-router feature to its file set, plus the external file
|
|
|
181
186
|
depend on it.
|
|
182
187
|
|
|
183
188
|
```
|
|
184
|
-
$ node
|
|
189
|
+
$ node agentmap.mjs --feature api
|
|
185
190
|
feature "api": 11 files
|
|
186
191
|
app/(chat)/api/chat/route.ts
|
|
187
192
|
app/(chat)/api/chat/schema.ts
|
|
@@ -200,7 +205,7 @@ external dependents (0): —
|
|
|
200
205
|
### `--features` — list features by size
|
|
201
206
|
|
|
202
207
|
```
|
|
203
|
-
$ node
|
|
208
|
+
$ node agentmap.mjs --features
|
|
204
209
|
features (4):
|
|
205
210
|
api (11 files)
|
|
206
211
|
login (1 files)
|
|
@@ -214,8 +219,8 @@ The files that matter most, ranked by PageRank importance (raw dependent degree
|
|
|
214
219
|
alongside).
|
|
215
220
|
|
|
216
221
|
```
|
|
217
|
-
$ node
|
|
218
|
-
|
|
222
|
+
$ node agentmap.mjs --hubs
|
|
223
|
+
agentmap: 154 files (sha 2becdb4)
|
|
219
224
|
hubs (PageRank importance):
|
|
220
225
|
lib/utils.ts (deg 52, pr 0.105171)
|
|
221
226
|
lib/db/schema.ts (deg 21, pr 0.073744)
|
|
@@ -233,7 +238,7 @@ The most important individual symbols across the repo, ranked by the identifier
|
|
|
233
238
|
(defaults to 30).
|
|
234
239
|
|
|
235
240
|
```
|
|
236
|
-
$ node
|
|
241
|
+
$ node agentmap.mjs --symbols 10
|
|
237
242
|
top 10 ranked symbols (Aider-style):
|
|
238
243
|
0.109902 lib/utils.ts → cn (FunctionDeclaration)
|
|
239
244
|
0.036013 lib/types.ts → ChatMessage (TypeAliasDeclaration)
|
|
@@ -254,8 +259,8 @@ that fits a token budget. Default budget is 8192 (1024 with `--focus`). `--focus
|
|
|
254
259
|
personalizes the ranking toward a file you're working on.
|
|
255
260
|
|
|
256
261
|
```
|
|
257
|
-
$ node
|
|
258
|
-
#
|
|
262
|
+
$ node agentmap.mjs --map --tokens 400
|
|
263
|
+
# agentmap (154 files, sha 2becdb4) — focus: global, budget ~400 tok
|
|
259
264
|
|
|
260
265
|
lib/utils.ts:
|
|
261
266
|
cn (FunctionDeclaration)
|
|
@@ -287,8 +292,8 @@ lib/db/schema.ts:
|
|
|
287
292
|
Focused on a working file — the ranking re-centers on what `lib/db/queries.ts` actually touches:
|
|
288
293
|
|
|
289
294
|
```
|
|
290
|
-
$ node
|
|
291
|
-
#
|
|
295
|
+
$ node agentmap.mjs --map --focus lib/db/queries.ts --tokens 350
|
|
296
|
+
# agentmap (154 files, sha 2becdb4) — focus: lib/db/queries.ts, budget ~350 tok
|
|
292
297
|
|
|
293
298
|
lib/utils.ts:
|
|
294
299
|
cn (FunctionDeclaration)
|
|
@@ -320,13 +325,25 @@ lib/errors.ts:
|
|
|
320
325
|
### `--print` — full map as JSON
|
|
321
326
|
|
|
322
327
|
Dumps the cached map (`hubs`, `features`, `rankedSymbols`, `files`) as one JSON object —
|
|
323
|
-
for piping into other tools.
|
|
328
|
+
for piping into other tools. Also includes a top-level `fileCount`.
|
|
324
329
|
|
|
325
330
|
```
|
|
326
|
-
$ node
|
|
331
|
+
$ node agentmap.mjs --print | jq '.hubs[0]'
|
|
327
332
|
"lib/utils.ts (deg 52, pr 0.105171)"
|
|
328
333
|
```
|
|
329
334
|
|
|
335
|
+
### Global flags
|
|
336
|
+
|
|
337
|
+
| Flag | Description |
|
|
338
|
+
|------|-------------|
|
|
339
|
+
| `--help` / `-h` | Print a usage block listing every flag and exit 0. |
|
|
340
|
+
| `--version` / `-v` | Print the version from `package.json` and exit 0. |
|
|
341
|
+
| `--json` | **Global modifier.** When present, every command prints exactly one JSON object to stdout (no prose). Shapes vary per command: `--json --hubs` → `{command,fileCount,sha,hubs:[string]}`, `--json --find X` → `{command,query,matches:[{file,name,kind}]}`, `--json --relates X` → `{command,file,pagerank,exports,imports,dependents,related}`, `--json --any X` → `{command,query,kind,…payload}`, etc. Bare `--json` (no query flag) → `{command:"build",fileCount,features,topHub}`. |
|
|
342
|
+
| `--install-hooks` | Copy `hooks/post-commit` into `.git/hooks/` (chmod 0755), ensure `.claude/agentmap.json` is in `.gitignore`, and print the Claude Code `settings.json` `PreToolUse` snippet. Exit 0 on success, stderr + exit 1 on failure. |
|
|
343
|
+
| `--mcp` | Start agentmap as a **stdio MCP server** so non-Claude-Code agents (Cursor, Cline, any MCP client) can call every flag as a first-class tool. |
|
|
344
|
+
|
|
345
|
+
**Exit-code contract:** `0` = success / match / help / version; `1` = query returned zero results (`--any`, `--find`, `--relates`, `--feature` with no match); `2` = usage error (missing required arg, unknown flag). Any token starting with `-` that matches no known flag prints an error to stderr and exits 2.
|
|
346
|
+
|
|
330
347
|
---
|
|
331
348
|
|
|
332
349
|
## The agent loop (the actual point)
|
|
@@ -337,22 +354,32 @@ to query the map before it serial-greps.
|
|
|
337
354
|
|
|
338
355
|
### 1. Auto-refresh on commit
|
|
339
356
|
|
|
340
|
-
[`hooks/post-commit`](./hooks/post-commit) rebuilds `.claude/
|
|
357
|
+
[`hooks/post-commit`](./hooks/post-commit) rebuilds `.claude/agentmap.json` after each
|
|
341
358
|
commit, detached + silenced so it never slows the commit. It skips during
|
|
342
359
|
rebase/merge/cherry-pick and no-ops if Node is missing.
|
|
343
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 prints the `.claude/settings.json`
|
|
369
|
+
snippet for the `PreToolUse` nudge hook (below). Manual alternative:
|
|
370
|
+
|
|
344
371
|
```bash
|
|
345
372
|
# from your repo root
|
|
346
373
|
cp hooks/post-commit .git/hooks/post-commit
|
|
347
374
|
chmod +x .git/hooks/post-commit
|
|
348
375
|
```
|
|
349
376
|
|
|
350
|
-
The hook auto-locates the builder: a local `
|
|
351
|
-
the installed `agentmap` binary, then `npx @raymondchins/agentmap`.
|
|
377
|
+
The hook auto-locates the builder: a local `agentmap.mjs`, then `scripts/agentmap.mjs`, then
|
|
378
|
+
the installed `agentmap` binary, then `npx --no-install @raymondchins/agentmap`.
|
|
352
379
|
|
|
353
380
|
### 2. Force the agent to use it — `PreToolUse` hook
|
|
354
381
|
|
|
355
|
-
[`hooks/
|
|
382
|
+
[`hooks/agentmap-nudge.mjs`](./hooks/agentmap-nudge.mjs) is a **non-blocking** `PreToolUse(Grep)`
|
|
356
383
|
hook for Claude Code. When a `Grep` looks like a dependency / who-imports / component-usage /
|
|
357
384
|
reuse search, it injects a reminder steering the agent to `agentmap --any` first. It never
|
|
358
385
|
denies the grep, and stays silent for raw-string / Tailwind-class / lowercase-HTML-tag
|
|
@@ -367,7 +394,7 @@ Wire it up in `.claude/settings.json`:
|
|
|
367
394
|
{
|
|
368
395
|
"matcher": "Grep",
|
|
369
396
|
"hooks": [
|
|
370
|
-
{ "type": "command", "command": "node ./hooks/
|
|
397
|
+
{ "type": "command", "command": "node ./hooks/agentmap-nudge.mjs" }
|
|
371
398
|
]
|
|
372
399
|
}
|
|
373
400
|
]
|
|
@@ -385,7 +412,8 @@ agent is steered to it the moment it reaches for a dependency-shaped grep.
|
|
|
385
412
|
Honesty first — this is deliberately a small, sharp tool, not a universal code-graph.
|
|
386
413
|
|
|
387
414
|
- **TS/JS only, by design.** Built on `ts-morph`. No Python, Go, Rust, etc. If your repo
|
|
388
|
-
isn't TypeScript/JavaScript, use a tree-sitter-based tool instead.
|
|
415
|
+
isn't TypeScript/JavaScript, use a tree-sitter-based tool instead. Support for other
|
|
416
|
+
languages is a possible future direction.
|
|
389
417
|
- **File-level import graph, not a full reference graph.** Edges come from static
|
|
390
418
|
`import` / re-export declarations and the named symbols crossing them. It does **not**
|
|
391
419
|
do call-site or full reference resolution — `--relates` tells you which files import a
|
|
@@ -407,19 +435,19 @@ Honesty first — this is deliberately a small, sharp tool, not a universal code
|
|
|
407
435
|
|
|
408
436
|
## Benchmark
|
|
409
437
|
|
|
410
|
-
|
|
438
|
+
Measured across **7 agent tasks on 3 real public repos** — reproducible with `node benchmark/bench.mjs <repo>`:
|
|
439
|
+
|
|
440
|
+
| Repo | Files | Tokens saved |
|
|
441
|
+
|------|------:|-------------:|
|
|
442
|
+
| [vercel/ai-chatbot](https://github.com/vercel/ai-chatbot) | 154 | **98.3%** |
|
|
443
|
+
| [colinhacks/zod](https://github.com/colinhacks/zod) | 367 | **99.2%** |
|
|
444
|
+
| [shadcn-ui/taxonomy](https://github.com/shadcn-ui/taxonomy) | 125 | **96.0%** |
|
|
411
445
|
|
|
412
|
-
- **
|
|
413
|
-
- **A. Understand file deps** (`lib/utils.ts`): baseline 583 tok → agentmap 517 tok (11.3% saved)
|
|
414
|
-
- **B. Find symbol** (`ChatMessage`): baseline 1950 tok → agentmap 20 tok (99% saved)
|
|
415
|
-
- **C. Repo overview** (tree + 3 hub files): baseline 3065 tok → agentmap 1127 tok (63.2% saved)
|
|
416
|
-
- Cold build (parse + PageRank + symbol graph): **~1.2s**. Warm cached query (`--hubs`,
|
|
417
|
-
clean tree): **~0.2s**.
|
|
446
|
+
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**.
|
|
418
447
|
|
|
419
|
-
|
|
420
|
-
end-to-end retrieval accuracy — there's no "did the agent fix the bug faster" eval yet.
|
|
448
|
+
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.
|
|
421
449
|
|
|
422
|
-
Full methodology,
|
|
450
|
+
Full methodology, per-repo tables, and all caveats: **[`./benchmark/RESULTS.md`](./benchmark/RESULTS.md)**.
|
|
423
451
|
|
|
424
452
|
---
|
|
425
453
|
|
|
@@ -431,8 +459,8 @@ Issues and PRs welcome. High-value directions:
|
|
|
431
459
|
- A real tokenizer behind the `--map` budget.
|
|
432
460
|
- Hardening feature detection for non-`app/`-router layouts.
|
|
433
461
|
|
|
434
|
-
Keep the dependency footprint minimal — `ts-morph` is the only runtime
|
|
435
|
-
feature.
|
|
462
|
+
Keep the dependency footprint minimal — `ts-morph` is the only runtime dependency (it bundles
|
|
463
|
+
the TypeScript compiler, ~10 MB installed), and keeping it that way is a feature.
|
|
436
464
|
|
|
437
465
|
## License
|
|
438
466
|
|