Skip to main content
Glama

LayerMap

English · 中文

npm GitHub stars npm downloads License

LayerMap tells your coding agent what calls a function and what changing it affects, up to the HTTP routes, in one call. With at most 15 requests, Claude Code on Opus 5.5 found 99.9% of affected endpoints with LayerMap vs 76.0% without; with no limit, it found about the same and cost 48% less, or 27% less without the task that gained most (benchmark).

Resolved by each language's compiler or type checker, not guessed from names by tree-sitter: calls through interfaces, base classes, templates and decorators link as the compiler links them, for TypeScript, JavaScript, Go, Python and Java.

A layered map of your codebase for coding agents. LayerMap gives Claude Code, Codex, CodeBuddy Code, Pi, DeepSeek Harness and other MCP clients read-only tools that answer, in one call, what an agent otherwise works out with dozens of searches:

  • What calls this, and what does changing it affect? Callers traced up to 8 levels, to the HTTP routes, handlers, jobs and commands they start from.

  • What does it call? Callees down to 8 levels.

  • What is here? Modules, each file's declarations, and every usage of a symbol.

  • What did my edit affect? The routes, jobs and commands the uncommitted changes reach, and the existing tests related to them.

It maps TypeScript, JavaScript, Go, Python and Java with each language's own compiler, so calls through interfaces, base classes, templates and decorators resolve as the compiler resolves them, including the ones text search misses. In WeChat mini-programs, it also links each page's and component's template (.wxml) to the methods it binds and the components it shows, and each event a component emits to the handlers the pages bind to it, so callers reach the pages.

Example

In Miniflux, one call on Storage.MarkFeedAsRead finds all four ways a request reaches it, each with its route:

DECLARATION internal/storage/entry.go: Storage.MarkFeedAsRead m656-680 exported
  ← called by internal/api/feed.go: handler.markFeedAsRead m140-155 @149
  ← called by internal/fever/handler.go: handler.handleWriteFeeds m492-519 @508
  ← called by internal/googlereader/handler.go: handler.markAllAsReadHandler m1261-1338 @1311
  ← called by internal/ui/feed_mark_as_read.go: handler.markFeedAsRead m14-30 @24
[1] internal/api/feed.go: handler.markFeedAsRead m140-155
  ← used as value by internal/api/api.go: Serve f25-84 @61 "PUT /v1/feeds/{feedID}/mark-all-as-read"
[1] internal/googlereader/handler.go: handler.markAllAsReadHandler m1261-1338
  ← used as value by internal/googlereader/handler.go: Serve f44-64 @62 "POST /reader/api/0/mark-all-as-read"
[1] internal/ui/feed_mark_as_read.go: handler.markFeedAsRead m14-30
  ← used as value by internal/ui/ui.go: Serve f18-180 @77 "POST /feed/{feedID}/mark-all-as-read"
… (the Fever API, then on down to main.go: main)

m and f mark methods and functions with their lines; @ is the line of the call, and the quoted route is what it is registered under: the HTTP method and the full path, with the /v1 prefix its subrouter adds. In Java, Python and TypeScript the route shows on the handler itself, as in @GetMapping("/{id}") route "GET /api/tasks/{id}".

Related MCP server: UCN

Results

Impact questions ("which HTTP endpoints does changing this affect?") on public Go, Python and Java projects, graded blind against truth sets cross-checked with each language's own toolchain:

With LayerMap

Without

Endpoints found, at most 15 requests (Claude Code on Opus 5.5, 6 tasks × 3 runs)

99.9%

76.0%

Cost / time at that limit (Opus 5.5)

+12% / +4%

Endpoints found, no request limit (Opus 5.5, 6 tasks × 2 runs)

100%

99.7%

Cost / time, no request limit (Opus 5.5, maps built ahead)

−48% / −33%; −27% / −21% without the task that gained most

Ripple tasks: runs leaving other features' tests passing (Opus 5.5, 4 tasks × 3 runs)

12 of 12

12 of 12

Endpoints found, at most 15 requests (gpt-5.5, 6 tasks × 3 runs)

97.9%

58.8%

Used unprompted by Claude Code / Codex (plugin installed, two rounds)

12 of 12 / 12 of 12

—

Endpoints found, no request limit (Claude Code / Codex, 0.1.5)

100% / 100%

99.0% / 100%

Claude Code cost, no request limit (0.1.5 re-run; first round −32%)

−33%

Codex input tokens, no request limit (current defaults)

+14%

Time, no request limit (Claude Code on claude-opus-5 / Codex, 0.1.5)

+25% / +20%

Failing tests the change check lists (Go / Python, functions made to fail)

100% / 94–98%

—

Ripple tasks: runs leaving other features' tests passing (Codex / Claude Code, 4 tasks × 6 runs with, × 3 without)

23 of 24 / 11 of 24

3 of 12 / 4 of 12

Everyday tasks, no impact analysis needed: done right / time (Claude Code and Codex, 8 tasks × 2 runs)

32 of 32 / +12–31%

32 of 32

With a tight budget, the map finds far more of the affected code, at 12–24% more cost or tokens. With no limit, both agents find nearly everything either way. Claude Code costs a third to a half less with the map. On Opus 5.5 it was also a third faster, though one task accounts for much of that gap and the maps were built ahead; on claude-opus-5 it was a quarter slower. Codex's current defaults already search lean, so the map no longer saves it tokens; at reasoning effort max, in the first round, it saved 55%. Codex with the map explores more widely, which takes longer. On requests whose obvious change breaks another feature, the change check helped Codex keep to the requested feature. Claude Code saw which tests of other features it had changed but often kept the broader change on purpose, so it showed no clear difference; on Opus 5.5 it broke nothing with or without the map, and the check cost 17% more. On small local tasks the map changed nothing but cost about a fifth more time and money. These are small samples on tasks written by LayerMap's authors. The report has the setup, the published tasks and the limitations.

How LayerMap differs

Other tools give agents part of this. LayerMap combines compiler accuracy with whole-chain traces in one local map:

Tree-sitter code graphs (codegraph, GitNexus, …)

Language servers and IDEs (Claude Code's LSP tool, Serena, JetBrains)

Embedding search (Claude Context, Augment)

LayerMap

How calls are linked

Matched by names, imports and framework rules, often with confidence scores

The compiler's own resolution

Not linked; similar code is retrieved

Resolved by each language's compiler or type checker

Callers traced to routes and handlers

In several tools, at varying depth

One level per request (JetBrains: 5 by default)

—

Up to 8 levels in one call

Kept as a map

Yes, with file watching

No, answered live by a running server

An index of code chunks

Yes, brought up to date on every call

Runs on your machine

Yes; some send anonymous telemetry

Yes

Usually with cloud embeddings

Yes, and sends nothing

Another tool fits better if you need:

  • more languages, since tree-sitter graphs cover 30 or more;

  • renaming and refactoring, from language servers;

  • search by meaning, from embedding search;

  • search across many repositories, with Sourcegraph.

Install

Claude Code

/plugin marketplace add coffeecoproject/layermap
/plugin install layermap@layermap

Codex

codex plugin marketplace add coffeecoproject/layermap
codex plugin add layermap@layermap

CodeBuddy Code

codebuddy plugin marketplace add coffeecoproject/layermap
codebuddy plugin install layermap@layermap

Pi

pi install npm:layermap

DeepSeek Harness

npx layermap setup dsh

This adds LayerMap to every dsh profile. Each session maps the project dsh was started in, and npx layermap remove dsh undoes it.

In every agent, start a new session in a Git repository and ask as usual. LayerMap tells the agent when the map helps. A session started in a folder holding several repositories, or one that moves to another repository, works too: each map tool call maps the repository its path names. The first time a session starts a version of LayerMap, npm installs that pinned layermap package into LayerMap's cache; later sessions start it from there, even offline.

Claude Code asks once before each map tool runs in a project. Choose "don't ask again", or run npx layermap allow claude to allow the plugin's read-only tools everywhere.

After an edit. When the agent changes code, project_check_changes lists what the change affects: the routes, jobs and commands that reach the changed functions, what the map cannot see, and the existing tests related to the change. When the changed code serves several areas (packages or modules), it names each one with its tests, and it names the existing tests the diff rewrote, so a change meant for one feature does not quietly change the others. Environment variables and configuration keys are linked by name only, which no compiler sees, so when the diff removes one from a file, the check names the files that still read or set the old name. In the same way, when the change reaches a route's handler or renames a route, it names the code and templates that request that path: a frontend's fetch, a generated API client, a redirect or a link. When the change adds an import between two modules of the project overview, it names it, and says when the two now depend on each other; whether that direction suits the project's layers is for the agent to judge. When a declaration the change adds reads almost the same as code the project already has, it names both, so the agent can use the existing code instead of a copy. When the change takes away the last call to a declaration, as when new code replaces old, it names that declaration, so the agent can delete what the change left behind. The map does not link a field or type to the code reading it, so for one the change touches, the check searches for its references and follows that code up to the entry points and tests, as possibly affected. It never writes or runs tests. In Claude Code and CodeBuddy Code the plugin asks the agent once, before it finishes, to run this check for each repository it edited code in and has not checked since, whether through its edit tools or shell commands, which count for the code files they name (changes another session makes in the same work tree do not count); the Pi extension does the same after the agent's own edits. Set LAYERMAP_STOP_CHECK=0 to turn that off. Codex and DeepSeek Harness are told to run it.

Without plugins: run npx layermap setup claude or npx layermap setup codex. Setup does three things:

  • registers the server;

  • lets its read-only tools run without a prompt;

  • adds one marked sentence to the agent's instructions file.

Setup is for one machine; for a whole team, have each member install the plugin. npx layermap remove … undoes it. For any other MCP client, run npx -y layermap mcp as a stdio server in the repository.

Requirements:

  • Node.js 22.22 or later.

  • macOS or Linux (x64 or arm64); Windows (x64 or arm64) is experimental.

  • A Git repository.

  • For Java projects, a JDK 21 or later.

How it works

The first call in a repository builds its map: seconds for a small project, a few minutes for a large one. Later calls re-analyze only what changed, so the map always matches the working tree.

Maps stay in your user cache (~/Library/Caches/layermap, ~/.cache/layermap or LAYERMAP_CACHE), never in the repository. LayerMap runs entirely on your machine and sends nothing anywhere (privacy, security).

Tool

Use

project_explore_map

A directory, a file, or a declaration's callers and callees (direction INCOMING or OUTGOING, depth up to 8).

project_search_map

Find declarations by words in their names, paths or documentation.

project_find_references

Every usage of a declaration, compiled from current source.

project_check_changes

What the uncommitted changes (or those since base) affect: changed and removed declarations, the routes, jobs and commands they reach, the areas that share the changed code, environment variables and configuration keys it removed that other files still use, code and templates that request the affected routes, new dependencies between modules and the cycles they close, new code that repeats existing code, what to check by hand, and related tests. Given tests, also the changed code none of those test files calls or requests through a route, and the entry points above it.

The same from the command line:

npx layermap explore src/api/users.ts --name createUser --direction INCOMING --depth 8
npx layermap search "invoice total"
npx layermap refs src/billing/tax.ts calculateTax
npx layermap check --base main
npx layermap check test/billing.test.ts   # also: what of the change this test does not run
npx layermap check --json                 # related tests by rank and what the map cannot follow, as JSON

FAQ

How long does the first map take? On a recent Mac:

  • Miniflux (400 Go files): about 3 s.

  • Polar's server (1,900 Python files): about a minute.

  • Conductor (1,500 Java and 1,300 TypeScript files): under two minutes.

What can't it see? Calls the compiler cannot resolve statically: dependency injection, unknown framework routing, reflection and computed names. The tools say where a trace stops, and a missing relationship does not prove absence. TypeScript and JavaScript types come from the packages installed in the project's node_modules (never mapped themselves); where they are not installed, as in a fresh worktree, values typed by them have no type to follow, and the tools name those packages.

Windows? Experimental. LayerMap's tests pass on Windows, but it has not yet been tried with Claude Code or Codex on a real Windows machine, so please test it on your own projects first and report what breaks. The Claude Code plugin's hooks need Git for Windows (they run in Git Bash); without it the map tools still work, and the session-start note and end-of-task check do not run.

Claude Code in print mode (claude -p)? Print mode, as of Claude Code 2.1, does not start the servers that installed plugins bring, so the map tools are missing there while the plugin's hooks still run. Pass the server yourself:

claude -p "..." --mcp-config '{"mcpServers":{"layermap":{"command":"npx","args":["-y","layermap","mcp"]}}}'

How do I remove it?

  • Claude Code: /plugin uninstall layermap@layermap.

  • Codex: codex plugin remove layermap@layermap.

  • CodeBuddy Code: codebuddy plugin uninstall layermap@layermap.

  • Pi: pi remove npm:layermap.

  • Then delete the cache directory.

Development

You need pnpm, Go 1.24 and a JDK 21+. A missing toolchain leaves its language unanalyzed.

Run pnpm install. On the first install pnpm asks which dependencies may run build scripts; allow esbuild only, since the SQLite package ships prebuilt binaries:

pnpm approve-builds esbuild '!@photostructure/sqlite'

Then run pnpm test, pnpm typecheck or pnpm lint.

pnpm package builds the npm package.

License

Apache-2.0. See LICENSE and NOTICE.

Available Tools

4 tools
project_check_changesWhat uncommitted changes affect (LayerMap)A
Read-onlyIdempotent

Use this once the edits are done, before reporting the work done: it lists what the uncommitted changes affect, from the changed functions up to the HTTP routes, jobs and commands that reach them, plus the existing tests related to them. Compares the working tree with a commit (HEAD by default, so uncommitted and untracked changes), finds the declarations the diff changed, removed or renamed, and follows their callers, and the code using a field or type, up to 8 levels. It reports, conclusion first: AFFECTED ENTRY POINTS reached through resolved calls, each route with its HTTP methods and full path and the chain to the change; POSSIBLY AFFECTED ones reached only through a call on an interface or base member, or through code that uses a changed field or type; REQUESTED BY, the code and templates outside the tests that request the path of a route whose handler the change reaches or a route it removed, found by text; EXISTING TESTS CHANGED, the tests that existed before the diff and whose code it changed or removed; SHARED BY, when tests reach the changed code through more than one area (package or module), so a change meant for one feature may change others; NAMES STILL USED ELSEWHERE, environment variables and configuration keys the diff removed from a file that other files still read or set, found by text; NEW MODULE DEPENDENCIES, imports between the modules of the project overview that the base did not have, and those that make two modules depend on each other, for you to judge against the project's layers; NEW COMPILE ERRORS, what the compiler reports on lines the diff left unchanged and did not report before, in code a tsconfig covers; PACKAGES NOT FOUND, packages the changed code needs that are not installed in this directory, whose types the trace then lacks; EXISTING CODE LIKE THE NEW CODE, declarations the diff adds whose code reads almost the same as code the project already has; LEFT WITHOUT CALLERS, declarations whose last callers outside the tests the diff removed or changed, and that nothing extends, implements, overrides or wires with a decorator; CHECK BY HAND for what a static map cannot follow (changed configuration, templates, migrations or dependency files, changed route registrations, declarations with no callers, calls by name on receivers of unknown type); and RELATED TESTS, the existing test files that call the changed code, import a changed file or sit beside it; given tests, NOT REACHED BY THE GIVEN TESTS, the changed declarations none of them calls or requests through a route, or uses when it is a field or type, with the entry points above them. It does not run or write tests: run the related ones if the change needs verifying; a failing or rewritten test of a feature the request is not about means the change leaked, so restore the test and narrow the change; a new dependency that runs against the layers or closes a cycle means moving what both modules need down rather than importing upward; new code like existing code means using the existing code, removing the old if the new replaces it, or having the existing code use the new where it is the one that can, unless the two are meant to differ, and changing existing code only where it is part of the task while telling the user of the rest; code left without callers means deleting it, with the tests that only test it, when the change replaced it; call it once when the edits are done; and confirm the entry points in source, since an empty list does not prove a change safe.

Inputs: base, path, tests.

project_explore_mapCallers, callees and impact of a change (LayerMap)A
Read-onlyIdempotent

Use this instead of grep to answer what calls a function or method, what changing it affects (callers traced up to entry points such as HTTP routes, handlers, jobs and commands), what it calls, and what a directory or file contains: one call returns the callers or callees up to 8 levels deep, with file paths and line numbers, for TypeScript, JavaScript, Go, Python and Java. Read the static project map, zooming from the whole project to one declaration. path "." or a directory lists modules, module imports, external packages and its files: with exported declarations when the listing is small, as file names and line counts by directory when larger, and as modules only when very large. Start here to see what exists before searching or reading. A file path lists its declarations and members, imports, importers and top-level statements. A file path with name (or Container.member), optionally narrowed by its start line, or with a line alone, shows that declaration's calls, callers (including uses as a value), writes, heritage, decorators and members, aggregated per related declaration with @line sites; closures and locals are folded into their named container. depth also expands the related declarations hop by hop: up to 8 in one direction, which traces callers up to entry points (INCOMING) or callees down (OUTGOING), and up to 3 for BOTH. To find what a change affects, select the declaration with direction INCOMING and a depth up to 8, continue from any NOT EXPANDED declarations the view names, then confirm the entry points in source. Test files and standard-library call targets are hidden and counted by default; includeTests and includeUnresolved show them. Views use kinds f function, c class, m method, p property, v variable, t type, i interface, e enum; numbers are 1-based source lines. In a declaration view, @n marks where a relationship occurs and +n counts further sites, which project_find_references lists; a quoted path after the sites is the route the call or value is registered under there: its HTTP methods when the registration names them, then its path joined with the prefixes of the routers it is registered on, as far as the same function or file sets them (a prefix added where a router is mounted or passed in is not included); route "…" after a decorator is the full route the decorator maps, its class's path joined with its own. Static relationships are grouped by the declaration that owns them. Callers are direct calls, uses as a value (stored, passed, returned or selected, then usually invoked through that value) and calls through an interface, type or base member that a declaration implements (dispatched from); dispatches to lists the members that implement an interface, type or base member, which a call through it may reach; trace stops names calls whose target is a function value, a member without a mapped implementation or a computed key, which only source reading can follow; possible callers by name are calls elsewhere, in the same language, of a member with a method's name on a receiver of unknown type (an untyped value, or one an unloaded package produced); they may or may not reach that method. Read source at the printed line ranges. The map is static: trace stops, possible callers by name, framework wiring and unresolved targets need source reading, and a missing relationship does not prove absence. When a page reports more entries, continue with offset and otherwise unchanged arguments.

Inputs: line, name, path, depth, +4 more.

project_find_referencesAll usages of a declaration (LayerMap)A
Read-onlyIdempotent

Use this to list every place a declaration is used (calls, imports, re-exports, reads and writes), compiled from current source: more complete than searching for its name. Compute usages of a mapped declaration from current source, including aliases, re-exports and non-call references. Select it with symbol {path,name,line?} as printed by project_explore_map or project_search_map (line is its start line when names repeat), or with an entityRef or locator {path,start,kind}. Broader and more expensive than the cached callers in project_explore_map; file or unsupported declarations may lack a reference target. path and kinds filter usage locations before paging. objects contains compact declarations; targetRef and reference ownerRef identify them. Read a reference at its line range. A file that several compiler contexts read (such as packages of one workspace) lists its references once per context, each with that context's configPath. Continue with nextCursor and unchanged conditions, including after an empty partial page. Filtered exhaustion and missing results do not prove absence.

Inputs: path, kinds, cursor, symbol, +3 more.

project_search_mapFind a declaration (LayerMap)A
Read-onlyIdempotent

Use this to find where a function, method, class or type is declared, by name or by words in its name, path or documentation, before exploring its callers with project_explore_map. Find declarations and files whose names, paths or source documentation match query terms. ANY (default) matches any term, ALL requires every term, LITERAL matches the exact text. Results are ranked by relevance and grouped by file with the declaration name, kind, 1-based line range and matched fields (kinds f function, c class, m method, p property, v variable, t type, i interface, e enum; numbers are 1-based source lines). Zoom into a result with project_explore_map({path,name}) or read its line range in the file. This is not a full-text search and does not prove absence; search the source text itself for exact text. Continue with offset and unchanged conditions.

Inputs: query (required), path, kinds, offset, +2 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.5/5.0

    Scored across 4 tools

    Disambiguation4/5

    Each tool has a recognizably different role: search finds declarations, explore reads structure/callers, find_references enumerates usages, and check_changes reports diff impact. The explore vs. find_references boundary is the only fuzzy spot, but descriptions explicitly contrast them (cached callers vs. broader, more expensive full reference computation). A competent agent should select correctly most of the time.

    Naming Consistency5/5

    All four tools share a project_ prefix followed by a verb_noun pattern: project_search_map, project_explore_map, project_find_references, project_check_changes. The action word differs meaningfully per tool, so names are both consistent and self-describing.

    Tool Count5/5

    Four tools map cleanly onto the four distinct verbs of a static code-map workflow (search, explore, enumerate references, assess a diff). Nothing feels redundant or missing at the count level; each tool clearly earns its place.

    Completeness4/5

    The surface covers the full discovery-to-verification lifecycle: locate a declaration, trace callers/callees to entry points, enumerate all usages, and evaluate change impact against a commit. Minor gaps remain, notably no full-text search (explicitly deferred to reading the source directly) and no standalone route/entry-point or module-dependency listing outside the diff-oriented tool, but these are workable given the descriptions.

    Maintenance

    ActivityActive
    ResponsivenessLimited data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables LLM agents to efficiently understand and navigate a codebase by providing semantic search over symbols and a reference graph, replacing expensive grep/glob calls with structured tools like definition lookup, caller/callee queries, and change-impact analysis.
      19 PyPI
      4
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI agents and terminal users to query codebases for callers, impact, tests, dependencies, and refactor previews using static AST analysis, with every match accounted for and uncertain relationships clearly marked.
      1,067 npm
      2
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables coding agents to query a precise, local call/type/data graph so they can find who calls what, what breaks when code changes, and which tests to run, with every answer traced to file:line.
      125 PyPI
      1
      Functional Source , Version 1.1, ALv2 Future
    • A
      license
      B
      quality
      B
      maintenance
      Enables coding agents to query a static AST-based call graph for TypeScript/JavaScript repositories, including who-calls, impact analysis, entry-to-dependency traces, hotspots, symbol search, and git-blame archaeology, with every result backed by source evidence chains.
      9
      1
      MIT