agentmap：coding agent が間違った file を読みにくくする TS/JS repo map
coding agent に中規模 frontend repository の変更を頼むとき、一番 context を消費するのは code を書く部分ではなく、code を探す部分だったりする。まず grep し、file をいくつも開き、barrel export や似た名前の helper に引っかかり、最後には関係の薄い内容まで prompt に入ってしまう。人間の reviewer も同じ問題に遭遇するが、agent は “それっぽい” を “本当に関係がある” と扱いやすい。
今日取り上げる raymondchins/agentmap は、この探索を local で query できる repo map に変えようとしている。対象は TypeScript / JavaScript / Vue SFC repository。ts-morph と TypeScript compiler で import、export、alias、workspace package、symbol relation を解析し、CLI と MCP server を提供する。agent は「この file の影響範囲はどこか」「この symbol はどこで定義されているか」「2000 token 以内で repo summary を出して」と聞ける。空の context から毎回 grep で探し直す必要を減らすわけだ。
GitHub repository page、README、Releases、Tags、LICENSE、package.json、公開 git history を 2026-07-27 時点で確認すると、raymondchins/agentmap は 45 stars、10 forks。GitHub page 上の主要言語は JavaScript、license は MIT。GitHub page の embedded repository data による作成時刻は 2026-06-13 11:29:36 UTC。公開 git history の最初の commit は d33bb26、commit time は 2026-06-13 11:20:24 UTC。現在の default branch main の latest commit は c5f0bfa、commit time は 2026-07-27 09:56:14 UTC。candidate discovery 時点での latest push は 2026-07-27 09:56:16 UTC。最新 GitHub Release は v0.20.0 で、GitHub release page は published time を 2026-07-26 17:09 UTC と表示している。対応する tag/commit は 9863810、git history 上の tag commit time は 2026-07-26 17:05:26 UTC。package.json による npm package name は @raymondchins/agentmap、version は 0.20.0、Node.js requirement は >=20、中心的な runtime dependency は ts-morph だ。
プロジェクト概要
| 項目 | 内容 |
|---|---|
| リポジトリ | raymondchins/agentmap |
| 位置づけ | coding agent 向けの local TS/JS repo map |
| Stars | 45 |
| Forks | 10 |
| 主要言語 | JavaScript |
| ライセンス | MIT |
| GitHub 作成時刻 | 2026-06-13 11:29:36 UTC |
| 最初の公開コミット | d33bb26、2026-06-13 11:20:24 UTC |
| 現在の default branch commit | c5f0bfa、2026-07-27 09:56:14 UTC |
| 最新 push | 2026-07-27 09:56:16 UTC |
| 最新 GitHub Release | v0.20.0、2026-07-26 17:09 UTC |
| npm package | @raymondchins/agentmap 0.20.0 |
| Node 要件 | >=20 |
| キーワード | repo map、code graph、MCP、CLI、PageRank、ts-morph、static analysis、coding agents |
解いているのは「code location」の隠れたコスト
多くの agent failure は、code を書けないことではなく、最初に間違った context を読んでしまうことから始まる。authentication helper を直してほしいだけなのに、re-export を source と勘違いしたり、似た名前の usage file を開いたり、最終的に本当の定義へ届く前に context を消費してしまう。TypeScript project の path alias、barrel export、workspace package、framework convention は、plain text search をさらに誤らせる。
agentmap の基本方針は、repository structure を queryable graph として先に作り、agent にその graph を聞かせることだ。README に出てくる core commands は分かりやすい。--find は symbol search、--relates は file の blast radius、--map --tokens N は token budget 内の repo digest、--any は入力を見て適切な query に route する。全 repository を prompt に入れるのではなく、「まずどの file を見るべきか」を一回の local query にする。
通常の grep との差は parser layer にある。agentmap は TypeScript compiler を使う。文字列や filename だけではなく、tsconfig paths、Vite/Webpack alias、Node #imports subpath、workspace import、barrel export chain など、TS/JS project でよく出てくる構造を解釈できる。agent にとっては、同名 symbol が大量に出る検索結果より、この差のほうが効く。
CLI、MCP、hook までを一つの loop にする
使い方を見ると、agentmap は単なる command line tool ではない。CLI、MCP server、agent skill、hooks をまとめている。軽く試すなら、TS/JS repository で次を実行するだけでよい。
npx @raymondchins/agentmap --any auth helperagent に継続的に使わせたい場合、README は hooks と skill の install を勧めている。
npx @raymondchins/agentmap --install-hooks
npx @raymondchins/agentmap --install-skillhooks のポイントは二つある。一つは commit 後に map を refresh し、agent が古い structure を読まないようにすること。もう一つは、agent が検索系 tool を雑に使いそうなタイミングで、先に agentmap を見るよう nudging することだ。repo map tool の失敗は、map を作れないことより、agent が存在を忘れることのほうが多い。この設計はそこを見ている。
MCP server によって、Claude Code、Cursor、Codex、Gemini、OpenCode、Copilot などの agent client から repo map を tool として呼べる。複数 agent や長い session では、CLI の使い方を model に覚えさせるより、この形のほうが安定しやすい。
面白いのは boundary を隠さないところ
README で見るべきなのは、「98% token saving」という数字そのものだけではない。その数字をどう説明しているかだ。agentmap は benchmark と eval を repository 内に置き、token saving が character estimate であることを明記している。また、単純な single-file lookup では cat + grep のほうが安い場合があるとも書いている。さらに、強い claim は TS/JS/Vue SFC に限定している。TypeScript compiler による module resolution が使えるからだ。
この boundary は重要だ。repo map tool は簡単に「AI に codebase を理解させる」という広すぎる slogan になってしまう。本当に難しいのは、知らないことを知っているふりをしないことだ。agentmap の他言語対応の説明も控えめで、README と ROADMAP は、--relates、BM25 search、PageRank map は比較的 port しやすい一方、--callers / --calls は TypeScript language service に依存しており、tree-sitter の名前一致でそれらしく見せるべきではない、と説明している。
この正直さは実運用では大事だ。tool 自身が弱い場面を知っているなら、agent も結果を絶対視せず、navigation aid として扱いやすい。
v0.20.0 の maintenance signal
今回の確認時点で、project には 146 public commits と 17 GitHub releases がある。最新 release v0.20.0 では --affected と --kind が追加された。前者は「どの test がこの file を cover しているか」を hop distance 付きで返す。後者は --find / --search を declaration kind で filter できる。tag message では 475 tests pass も示されている。
この二つは、tool が “agent に code を探させる” ところから “agent に変更リスクを見積もらせる” 方向へ伸びていることを示している。agent が file を変更するなら、依存先だけでなく、どの test が効きそうかも知りたい。--kind は symbol search の noise を減らし、component、function、class などに絞りやすくする。
repository には EVAL.md、benchmark/RESULTS.md、ROADMAP.md、多くの node tests、SECURITY.md もある。45 stars の小さな project としては、star 数よりもこうした検証用 file のほうが maintenance signal になる。
向いている場面
一つ目は TypeScript / JavaScript の monolithic application、特に Next.js、Vite、React、Vue SFC、monorepo workspace のように alias と re-export が多い project だ。file 間の関係が複雑なほど、repo map の価値が出る。
二つ目は coding agent を日常的に使う team だ。IDE jump の代替として見る必要はない。問題は、agent には人間のような project memory がなく、session ごとに同じ探索を繰り返すことだ。local で再現可能な structure map を渡せば、その探索コストを下げられる。
三つ目は code を外部に出しにくい project だ。agentmap の README は server、vector DB、embedding API、telemetry がないことを強調している。local に repository を解析し、cache も controlled location に置くため、local context retrieval layer として扱いやすい。
注意点
第一に、language scope は狭い。現在強いのは TS/JS/Vue SFC だ。core repository が Go、Rust、Python、Java なら、agentmap はそのまま答えにはならない。README には forks/ports への言及があるが、official project ではない。
第二に、完全な semantic index ではない。中心は file-level import graph、symbol index、PageRank、部分的な call query であり、Sourcegraph、IDE language server、security analysis platform の代替ではない。
第三に、benchmark number は task ごとに読むべきだ。whole-repo digest、impact analysis、symbol location には向いている。一方で小さな file を一つ見るだけなら、直接開いたほうが速いこともある。agent の navigation layer として見るのが自然だ。
第四に、hook は agent workflow に介入する。個人 project では便利でも、team repository では何を install し、どの file を書き、どう uninstall するかを確認してから採用したほうがよい。
まとめ
raymondchins/agentmap の価値は、また一つ “AI repo context” wrapper を作ったことではない。coding agent の具体的な弱点、つまり code を探す step が高コストで不正確になりがちな点を狙っていることだ。TS/JS project に対して TypeScript compiler で local queryable repo map を作る、という切り口は狭いが実用的だ。
Next.js、Vite、Vue、TypeScript monorepo を保守していて、日常的に agent に変更を任せているなら、agentmap は試す価値がある。business logic を理解してくれるわけでも、変更の正しさを保証するわけでもない。それでも、agent が手を動かす前に間違った file を読む回数を減らせるなら、それだけで十分に意味がある。