agentmap

Stop your coding agent from reading the wrong files.

Ask "what breaks if I change this?" and grep hands back a pile where 40% of the files don't actually depend on it. agentmap answers the same question at 100% precision — measured, on public repos, reproducibly.

npx @raymondchins/agentmap --relates src/lib/auth.ts

Your agent re-learns your codebase every session, grepping to find what connects to what and burning tokens before it writes a line. agentmap gives it a queryable, PageRank-ranked import/symbol map instead — built with ts-morph, the real TypeScript compiler, so it resolves what string matching cannot.

n=42 dependents / n=75 definitions across zod, zustand and hono at pinned commits. Ground truth is derived at runtime by an independent resolver, not hand-authored. Re-run it yourself: npm run eval. Full method + per-repo numbers: EVAL.md.

Precision is the point: every wrong file your agent opens is context spent being misled. --relates returns the full blast radius, so it costs more tokens than a bare grep -l file list — and that trade is stated plainly in the eval, not hidden.

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

Quickstart

No install needed:

npx @raymondchins/agentmap --any <query>

…or run it directly from a checkout:

node agentmap.mjs --any <query>

The first run builds and caches the map to .claude/agentmap/map.json (add .claude/agentmap/ to .gitignore). Subsequent runs serve the cache when the tree is clean and HEAD is unchanged, and silently rebuild from disk when there are uncommitted .ts/.tsx/.js/... edits — so queries always reflect your in-flight work.

Run with no flag to build + print a one-line summary:

$ node agentmap.mjs
agentmap: 154 files | 4 features | top hub: lib/utils.ts (deg 52, pr 0.105171)

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). Every figure is captured tool output (node benchmark/bench.mjs <repo> at the pinned sha):

Context tokens the agent burns to answer each question — token est = chars/4, applied to both sides.

That's the agent reaching the same answer on 58× fewer tokens overall — and the pattern holds across zod (367 files, 99.2%) and 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.

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 (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 93.3% of the time (naive grep 80%) at ~2.4× fewer tokens, and identifies a module's dependents at 100% precision / 99.2% recall (grep 100% recall but 59.9% precision). Fixtures are pinned to exact commits, so those numbers are re-derivable rather than whatever upstream happened to look like the day they were taken. 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 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, ~62k★ (2026-07-26)) 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.

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). 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 convenient but not unique — CodeGraph and others auto-sync and auto-configure agent CLIs too; we don't claim it as a moat.

The agent loop (staying current, staying used)

A common failure of repo-map tools: they build a beautiful map, and then the agent forgets it exists and greps anyway. A map the agent doesn't open is just dead weight.

agentmap closes that loop. Two hooks (in ./hooks/) do the work: the map refreshes itself after every commit, and the agent gets nudged to query it before it serial-greps. You wire it once — then it stays current on its own, and stays used.

This wiring is table stakes, not the moat — CodeGraph and other tools also auto-sync (via native OS file watchers) and auto-configure agent CLIs. agentmap ships it because it's genuinely useful; the actual point of agentmap is the compiler-grade TS/JS accuracy the map is built on.

1. Auto-refresh on commit

hooks/post-commit rebuilds .claude/agentmap/map.json after each commit, detached + silenced so it never slows the commit. It skips during rebase/merge/cherry-pick and no-ops if Node is missing.

The hooks ship inside the npm package. The simplest setup:

npx @raymondchins/agentmap --install-hooks

This copies hooks/post-commit into .git/hooks/, sets it executable, ensures .claude/agentmap/ is in .gitignore, and auto-wires the PreToolUse nudge hook into .claude/settings.json (merge-safe + idempotent) so map enforcement is on by default — no manual paste. Manual alternative for just the post-commit hook:

# from your repo root
cp hooks/post-commit .git/hooks/post-commit
chmod +x .git/hooks/post-commit

The hook resolves the builder to the installed package — node_modules/.bin/agentmap, a PATH agentmap binary verified to be @raymondchins/agentmap, then npx @raymondchins/agentmap. It never runs a repo-local ./agentmap.mjs unless you opt in with AGENTMAP_HOOK_ALLOW_LOCAL=1 (for developing agentmap itself), so an attacker-planted agentmap.mjs can't execute on your next commit.

2. Force the agent to use it — PreToolUse hook

hooks/agentmap-nudge.mjs is a non-blocking hook for Claude Code that covers both the Grep tool and raw Bash text-searchers (grep/rg/egrep/fgrep/ag/ack). When either looks like a dependency / who-imports / component-usage / reuse / where-is-symbol search, it injects a reminder steering the agent to agentmap --any first. It never denies the call, and stays silent for raw-string / Tailwind-class / lowercase-HTML-tag sweeps and for pipe-filtered commands like ps aux | grep node — so it's high-signal, not nagging.

Fires on: import/require/export/from '...' patterns, JSX component tags (<Hero, <ProviderCard), explicit intent words (where is, who imports, reuse, existing component), and — in both the Grep tool and the Bash branch — bare multi-hump PascalCase identifiers (ProviderCard, TopProviders) that almost always mean "where is this symbol / who uses it". The Bash branch additionally only fires when the searcher is the primary command (at the start, or after ;/&&); piped log-filters stay silent.

All four nudge/gate variants (this one, Codex, Gemini, OpenCode) also self-gate on project presence: since they ship at user/global scope too (plugin bundle, ~/.gemini, ~/.codex, ~/.config/opencode), they walk up from the tool call's cwd to the filesystem root looking for node_modules/@raymondchins/agentmap or a built .claude/agentmap/map.json before doing anything else, so a repo with no agentmap stays silent instead of nagging (or, for Codex, denying a grep it has no business denying).

--install-hooks writes both matchers into .claude/settings.json for you (merge-safe — preserves existing settings, won't duplicate on re-run). The single hook file dispatches internally on tool_name. For reference, or to wire it by hand:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Grep",
        "hooks": [{ "type": "command", "command": "node ./hooks/agentmap-nudge.mjs" }]
      },
      {
        "matcher": "Bash",
        "hooks": [{ "type": "command", "command": "node ./hooks/agentmap-nudge.mjs" }]
      }
    ]
  }
}

That's the "forced to use it" in the tagline: the map stays current on its own, and the agent is steered to it the moment it reaches for a dependency-shaped grep or Bash search.

3. Agent skills (Cursor, Claude Code, Codex, OpenCode, Gemini, Antigravity, Copilot)

npx @raymondchins/agentmap --install-skill

…or grab just the skill (no agentmap flags) via the skills CLI — agentmap ships the skills/agentmap/SKILL.md layout it expects:

npx skills add raymondchins/agentmap

--install-skill copies packaged SKILL.md files and a Cursor rule (.cursor/rules/agentmap.mdc, alwaysApply: true) into the current repo or global agent directories. Paths follow each platform's official skill-directory conventions. Options:

agentmap --install-skill --platform cursor           # Cursor rule only (project)
agentmap --install-skill --platform claude           # .claude/skills/agentmap/SKILL.md
agentmap --install-skill --platform codex            # .codex/skills/ (project) or ~/.codex/skills/ (global)
agentmap --install-skill --platform opencode         # .opencode/skills/ (project) or ~/.config/opencode/skills/ (global)
agentmap --install-skill --platform gemini           # .gemini/skills/ (project); global ~/.gemini/skills/ (Windows global: ~/.agents/skills/)
agentmap --install-skill --platform antigravity      # .agents/skills/ (project) or ~/.gemini/config/skills/ (global)
agentmap --install-skill --platform copilot          # .copilot/skills/ or ~/.copilot/skills/
agentmap --install-skill --global --platform claude  # ~/.claude/skills/...
agentmap --install-skill --platform agents           # legacy .agents/skills/ (project or global); excluded from default `all`
agentmap --install-skill --dry-run                   # preview paths, no writes

--platform all installs: claude, cursor, codex, opencode, gemini, antigravity, copilot (not legacy agents).

Some platforms also get always-on docs and hooks in the same command:

Codex and OpenCode share one repo-root AGENTS.md on project install. Existing content outside the marked block is preserved.

Pair with --install-hooks (Claude Code) or --mcp (Cursor MCP).

4. Claude Code plugin (one-command bundle)

Prefer the plugin over --install-skill/--install-hooks if you're on Claude Code and want the skill, the PreToolUse grep/Bash nudge, and the stdio MCP server in a single install that auto-updates:

# in Claude Code
/plugin marketplace add raymondchins/agentmap
/plugin install agentmap@agentmap

The plugin bundles: the packaged SKILL.md, the PreToolUse nudge (both the Grep tool and Bash text-searchers, via ${CLAUDE_PLUGIN_ROOT}), and the stdio MCP server (npx -y @raymondchins/agentmap --mcp, so ts-morph is fetched on demand — the plugin cache ships no node_modules).

One thing the plugin can't do: install the git post-commit hook. Claude Code plugins can't write into .git/hooks/, so the auto-refresh-on-commit still needs a one-time npx @raymondchins/agentmap --install-hooks in each repo (it also wires the nudge into .claude/settings.json, harmlessly redundant with the plugin's copy). Without it the map still rebuilds on any dirty query — you just lose the commit-time refresh.

Onboarding by platform

Enforcement isn't uniform — some CLIs get a live hook that actively steers grep to agentmap, some get an MCP server the agent can call, and some are docs-only (a skill/rule the agent may or may not consult). Honest matrix:

Cursor MCP — copy-paste .cursor/mcp.json (Cursor's --mcp wiring is a documented dead-end otherwise; drop this at your repo root):

{
  "mcpServers": {
    "agentmap": {
      "command": "npx",
      "args": ["-y", "@raymondchins/agentmap", "--mcp"]
    }
  }
}

Then Cursor exposes the 11 query tools (any, find, relates, map, hubs, features, feature, symbols, search, callers, calls). Run agentmap --doctor any time to see what's wired vs missing.

Uninstall

agentmap only writes files into your repo/home — remove them to fully uninstall. agentmap --doctor lists every path it wrote, and every docs merge lives inside an <!-- agentmap:begin/end --> (or # agentmap:begin/end) fence, so deleting just that block leaves the rest of your AGENTS.md / GEMINI.md intact.

Troubleshooting

The --any router

Don't want to learn eight flags? You don't have to. Throw anything at --any — a filename, a function, a feature, even a raw string — and it figures out what you meant, returning the first layer that hits:

--any <query>
   │
   ├─ 1. FILE     exact path → unique basename → unique substring
   ├─ 2. SYMBOL   exported name contains the query (across all files)
   ├─ 3. FEATURE  app/-router feature name contains the query
   └─ 4. CONTENT  live `git grep` (tracked + untracked) — never stale

Layers 1–3 read the cached structural map (fast, ranked). Layer 4 is a live disk read via git grep -F, so raw strings, copy, Tailwind classes, and config values the structural graph never indexes still resolve instead of coming up empty.

Symbol hit (query resolved to a symbol → full block):

$ node agentmap.mjs --any cn
[structure] 1 symbol, 0 feature match for "cn"
  lib/utils.ts → cn (FunctionDeclaration)

Ambiguous file hit (query matched multiple files → narrow it):

$ node agentmap.mjs --any utils
[structure] "utils" matched 3 files — narrow it:
  lib/utils.ts
  lib/db/utils.ts
  tests/prompts/utils.ts

Content fallback (no file/symbol/feature match → live git-grep):

$ node agentmap.mjs --any streamText
[content] 13 lines:
app/(chat)/api/chat/route.ts:8:  streamText,
app/(chat)/api/chat/route.ts:194:        const result = streamText({
artifacts/code/server.ts:1:import { streamText } from "ai";
artifacts/code/server.ts:18:    const { fullStream } = streamText({
artifacts/code/server.ts:40:    const { fullStream } = streamText({
artifacts/sheet/server.ts:1:import { streamText } from "ai";
artifacts/sheet/server.ts:11:    const { fullStream } = streamText({

Commands

Every snippet below is representative output (long lists trimmed) from running agentmap against the public 154-file Next.js repo vercel/ai-chatbot (sha 2becdb4).

--any <q> — the router (file → symbol → feature → live content)

See The --any router above. Default first move for any "where/what/who" question.

--find <q> — reuse-before-rebuild symbol search

Find every symbol whose name contains the query — exported symbols plus non-exported top-level declarations. Use it before writing a new util or component to check what already exists (a private helper counts as reusable too).

$ node agentmap.mjs --find Message
find "Message": 55 match
  hooks/use-messages.tsx → useMessages (FunctionDeclaration)
  lib/errors.ts → getMessageByErrorCode (FunctionDeclaration)
  lib/types.ts → messageMetadataSchema (VariableDeclaration)
  lib/types.ts → MessageMetadata (TypeAliasDeclaration)
  lib/types.ts → ChatMessage (TypeAliasDeclaration)
  lib/utils.ts → convertToUIMessages (FunctionDeclaration)
  lib/utils.ts → getTextFromMessage (FunctionDeclaration)
  tests/helpers.ts → generateTestMessage (FunctionDeclaration)
  app/(chat)/actions.ts → generateTitleFromUserMessage (FunctionDeclaration)
  …

--search <q> — BM25 lexical search for vague queries

When you don't know the exact symbol name — the query an agent actually types — --search ranks symbols by BM25 lexical relevance over split-identifier tokens (the symbol name, its file's path segments, feature, and kind), fused with file PageRank so a strong hit in an important file wins ties. No embeddings, no vector DB; the index is built into map.json. The same ranker is wired into --any as a rung that fires only when exact file/symbol matching found nothing, so exact routing is unchanged.

$ node agentmap.mjs --search "auth retry logic"
search "auth retry logic": 3 match
  src/authRetry.ts → retryWithBackoff (FunctionDeclaration)  [6.83]
  …

Stopwords (the, that, of, …) are dropped, so --search "the function that dedupes symbols" works. Also available as the search MCP tool.

--relates <path> — blast radius + transitive relevance

The file's own block (exports / imports / direct dependents) plus a random-walk relevance list (personalized PageRank on the bidirectional import graph) — the files most related to the target, transitively, not just its direct importers.

$ node agentmap.mjs --relates lib/db/schema.ts
relates: lib/db/schema.ts  (pr 0.073744)
exports (14): user(VariableDeclaration), User(TypeAliasDeclaration), chat(VariableDeclaration), Chat(TypeAliasDeclaration), message(VariableDeclaration), DBMessage(TypeAliasDeclaration), …
imports (0): —
dependents (21): hooks/use-active-chat.tsx, lib/types.ts, lib/utils.ts, components/chat/artifact.tsx, components/chat/message.tsx, lib/db/queries.ts, app/(chat)/api/chat/route.ts, …
related (random-walk relevance):
  lib/utils.ts (0.0476)
  lib/types.ts (0.0376)
  components/chat/artifact.tsx (0.0372)
  components/chat/icons.tsx (0.0264)
  components/chat/message.tsx (0.0237)
  lib/db/queries.ts (0.0225)
  app/(chat)/api/chat/route.ts (0.0218)
  …

For a file carrying a React Server Components directive prologue, the output adds one more line — boundary: 'use client' (client component) or boundary: 'use server' (server module/actions) (rsc: 'client' | 'server' in --json) — right after dependents. This is additive and optional: repos with no 'use client'/'use server' directives never see the line.

--callers <sym> — compiler-accurate call graph (experimental)

Who actually calls a symbol, resolved by the TypeScript language service (ts-morph findReferencesAsNodes) — not tree-sitter name-matching. This is symbol-level blast radius: a type-position mention (typeof foo), a re-export, a bare value reference (const x = foo), or a same-named private local in another file is a different symbol and is never mis-attributed. --in <path> disambiguates a name defined in more than one file (exported definitions win over same-named private locals); results are ranked by caller-file PageRank and capped.

$ node agentmap.mjs --callers getMessageByErrorCode
callers of getMessageByErrorCode  [lib/errors.ts]: 3 call sites
  app/(chat)/api/chat/route.ts:88 → POST
  lib/db/queries.ts:142 → saveMessage
  components/chat/message.tsx:57 → PureMessage

JSX counts as a call site. <Foo /> compiles to React.createElement(Foo, …) (classic runtime) or jsx(Foo, …) (automatic runtime) — either way it's an invocation, so a component's callers include everywhere it's rendered, not just plain foo() calls. <Foo.Bar /> resolves to Bar, not the Foo namespace; <Foo>...</Foo> counts once (the closing tag isn't a second call site); an intrinsic tag (<div>) resolves to nothing in-project and produces no edge.

$ node agentmap.mjs --callers Button
callers of Button  [components/ui/button.tsx]: 25 call sites
  components/ai-elements/message.tsx:93 → MessageAction
  components/ai-elements/message.tsx:263 → MessageBranchPrevious
  components/ui/sidebar.tsx:249 → SidebarTrigger
  components/ui/alert-dialog.tsx:158 → AlertDialogAction
  components/ui/dialog.tsx:72 → DialogContent
  …

Before 0.17.0, JSX wasn't a recognized call shape at all, so that same query returned 0 call sites — a plain rg '<Button' beat the tool outright. Captured on vercel/ai-chatbot at c2f8235; reproduce it by running the query against that commit.

A deliberate deep query: it lazily spins up the TS type-checker (a few seconds on a large repo) only when invoked — the map build and every other query never pay that cost, and nothing is persisted. Accurate on statically-resolvable calls; dynamic dispatch, reflection, and string-keyed access are beyond any static tool. Also available as the callers MCP tool.

--calls <sym> — outgoing call graph (experimental)

The companion to --callers: which in-project symbols a symbol invokes. Each call and new X() site inside its body is resolved by the type checker (getDefinitionNodes), which follows an imported / re-exported binding through to the real declaration — so a same-named local elsewhere is never confused for the imported one. node_modules and TypeScript built-ins (console.log, Array.map, …) are excluded; dynamic dispatch, computed member access, and higher-order callees are honestly skipped.

$ node agentmap.mjs --calls extractFacts
extractFacts calls  [agentmap.mjs]: 15 in-project targets
  agentmap.mjs:756 → makeProject (FunctionDeclaration)
  agentmap.mjs:944 → rel (VariableDeclaration)
  agentmap.mjs:952 → excluded (VariableDeclaration)
  …

JSX counts as an outgoing call too, for the mirror-image reason: a component whose body is nothing but return <Container><Sidebar /></Container> has no CallExpression in it, so before this fix it reported zero outgoing calls even though it clearly depends on both. Each <Foo /> / <Foo>...</Foo> in the body now resolves to its target declaration the same way a plain call does — the printed (kind) is the target's own declaration kind (FunctionDeclaration, etc.), not "JSX", since resolution is unchanged, only call-site detection is:

$ node agentmap.mjs --calls AppSidebar
AppSidebar calls  [components/chat/app-sidebar.tsx]: 35 in-project targets
  components/ui/tooltip.tsx:21 → Tooltip (FunctionDeclaration)
  components/ui/tooltip.tsx:33 → TooltipContent (FunctionDeclaration)
  components/ui/sidebar.tsx:144 → Sidebar (FunctionDeclaration)
  components/ui/sidebar.tsx:379 → SidebarContent (FunctionDeclaration)
  …

Same repo and commit: this returned 6 targets before 0.17.0 — only the plain hook and helper calls — and 35 after, because the 29 components it renders now count too.

Same lazy, out-of-band model as --callers (builds a Project only on the query, nothing persisted). Also the calls MCP tool. JSX closes a real gap here — it doesn't change what's still out of reach: the node_modules/dynamic-dispatch/computed-member/higher-order limits above still apply.

Going transitive — --depth N. Both --callers and --calls accept --depth N (default 1, max 5) for an N-hop closure: --callers foo --depth 3 is the transitive blast radius ("everything that reaches foo, up to 3 hops"); --calls foo --depth 3 is the dependency cone ("everything foo pulls in"). It BFS-traverses the same single warm Project — no extra build — with cycle detection and node caps so a hub can't explode; each result is tagged with its depth and a via parent. --depth 1 is the default single-hop query.

$ node agentmap.mjs --callers leaf --depth 2
callers of leaf  [src/chain.ts]: 2 callers within depth 2
  src/chain.ts:2 → mid [depth 1]
  src/chain.ts:3 → top [depth 2]

--feature <name> — files that make up a feature

Resolves a Next.js app/-router feature to its file set, plus the external files that depend on it.

$ node agentmap.mjs --feature api
feature "api": 11 files
  app/(chat)/api/chat/route.ts
  app/(chat)/api/chat/schema.ts
  app/(chat)/api/document/route.ts
  app/(chat)/api/history/route.ts
  app/(chat)/api/messages/route.ts
  app/(chat)/api/models/route.ts
  app/(chat)/api/suggestions/route.ts
  app/(chat)/api/vote/route.ts
  app/(auth)/api/auth/guest/route.ts
  app/(chat)/api/files/upload/route.ts
  app/(chat)/api/chat/[id]/stream/route.ts
external dependents (0): —

--features — list features by size

$ node agentmap.mjs --features
features (4):
  api (11 files)
  login (1 files)
  register (1 files)
  chat (1 files)

--hubs — most important files (PageRank)

The files that matter most, ranked by PageRank importance (raw dependent degree shown alongside).

$ node agentmap.mjs --hubs
agentmap: 154 files (sha 2becdb4)
hubs (PageRank importance):
  lib/utils.ts (deg 52, pr 0.105171)
  lib/db/schema.ts (deg 21, pr 0.073744)
  lib/types.ts (deg 23, pr 0.067589)
  components/chat/artifact.tsx (deg 15, pr 0.036882)
  components/chat/icons.tsx (deg 27, pr 0.035378)
  lib/errors.ts (deg 9, pr 0.032787)
  lib/db/queries.ts (deg 14, pr 0.030085)
  …

--symbols [N] — top ranked symbols (Aider-style)

The most important individual symbols across the repo, ranked by the identifier graph (defaults to 30).

$ node agentmap.mjs --symbols 10
top 10 ranked symbols (Aider-style):
  0.109902  lib/utils.ts → cn (FunctionDeclaration)
  0.036013  lib/types.ts → ChatMessage (TypeAliasDeclaration)
  0.025686  components/chat/artifact.tsx → ArtifactKind (TypeAliasDeclaration)
  0.022461  lib/errors.ts → ChatbotError (ClassDeclaration)
  0.021068  lib/types.ts → CustomUIDataTypes (TypeAliasDeclaration)
  0.020872  lib/db/schema.ts → Document (TypeAliasDeclaration)
  0.020555  components/ai-elements/suggestion.tsx → Suggestion (VariableDeclaration)
  0.020555  lib/db/schema.ts → Suggestion (TypeAliasDeclaration)
  0.018124  lib/db/schema.ts → DBMessage (TypeAliasDeclaration)
  0.015034  lib/errors.ts → ErrorCode (TypeAliasDeclaration)

--map [--tokens N] [--focus <path>] — token-budgeted ranked digest

The token-budgeted digest (Aider's killer feature): a ranked, files-and-symbols summary that fits a token budget. Default budget is 8192 (1024 with --focus). --focus <path> personalizes the ranking toward a file you're working on.

$ node agentmap.mjs --map --tokens 400
# agentmap (154 files, sha 2becdb4) — focus: global, budget ~400 tok

lib/utils.ts:
  cn (FunctionDeclaration)
  generateUUID (FunctionDeclaration)

lib/types.ts:
  ChatMessage (TypeAliasDeclaration)
  CustomUIDataTypes (TypeAliasDeclaration)
  ChatTools (TypeAliasDeclaration)
  Attachment (TypeAliasDeclaration)

components/chat/artifact.tsx:
  ArtifactKind (TypeAliasDeclaration)
  UIArtifact (TypeAliasDeclaration)
  Artifact (VariableDeclaration)

lib/errors.ts:
  ChatbotError (ClassDeclaration)
  ErrorCode (TypeAliasDeclaration)

lib/db/schema.ts:
  Document (TypeAliasDeclaration)
  Suggestion (TypeAliasDeclaration)
  DBMessage (TypeAliasDeclaration)

# ~387 tokens (14 files shown)

Focused on a working file — the ranking re-centers on what lib/db/queries.ts actually touches:

$ node agentmap.mjs --map --focus lib/db/queries.ts --tokens 350
# agentmap (154 files, sha 2becdb4) — focus: lib/db/queries.ts, budget ~350 tok

lib/utils.ts:
  cn (FunctionDeclaration)
  generateUUID (FunctionDeclaration)
  getDocumentTimestampByIndex (FunctionDeclaration)
  fetcher (VariableDeclaration)
  getTextFromMessage (FunctionDeclaration)
  convertToUIMessages (FunctionDeclaration)
  fetchWithErrorHandlers (FunctionDeclaration)
  sanitizeText (FunctionDeclaration)

lib/db/schema.ts:
  DBMessage (TypeAliasDeclaration)
  Suggestion (TypeAliasDeclaration)
  Document (TypeAliasDeclaration)
  Chat (TypeAliasDeclaration)
  User (TypeAliasDeclaration)
  chat (VariableDeclaration)
  document (VariableDeclaration)
  message (VariableDeclaration)

lib/errors.ts:
  ChatbotError (ClassDeclaration)
  ErrorCode (TypeAliasDeclaration)

# ~324 tokens (8 files shown)

--print — full map as JSON

Dumps the cached map (hubs, features, rankedSymbols, files) as one JSON object — for piping into other tools. Also includes a top-level fileCount.

$ node agentmap.mjs --print | jq '.hubs[0]'
"lib/utils.ts (deg 52, pr 0.105171)"

--export <mermaid|dot> — visualize the import graph

Serializes the file import graph (nodes = files, edges = imports, top-N by PageRank, with three light style tiers) as Graphviz DOT or Mermaid — paste straight into mermaid.live, a GitHub README mermaid block, or dot -Tsvg. --focus <path> scopes to a file's 1-hop neighborhood. It reads the cached map only (no ts-morph Project), and prints graph text to stdout