LayerMap
LayerMap provides read-only MCP tools to explore a static code map, find references, and assess the impact of changes.
Explore directories, files, and declarations and trace callers or callees up to 8 levels, including entry points such as HTTP routes, handlers, jobs, and commands.
Search for declarations by name, path, or documentation with kind and match filters.
Find all usages of a declaration, including calls, imports, re-exports, reads, and writes.
Check uncommitted or branch changes for affected entry points, related tests, shared areas, removed env/config names still used, new module dependencies/cycles, compile errors, missing packages, similar existing code, and declarations left without callers.
Optionally include tests or unresolved targets in exploration, and specify test files to see changed code they do not reach.
Supports TypeScript, JavaScript, Go, Python, and Java via compiler/type-checker resolution; the map is static and does not run or write tests.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@LayerMap what calls createUser in src/api/users.ts, traced up to entry points?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
LayerMap
English · 中文
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 ( | 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 | +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@layermapCodex
codex plugin marketplace add coffeecoproject/layermap
codex plugin add layermap@layermapCodeBuddy Code
codebuddy plugin marketplace add coffeecoproject/layermap
codebuddy plugin install layermap@layermapPi
pi install npm:layermapDeepSeek Harness
npx layermap setup dshThis 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 |
| A directory, a file, or a declaration's callers and callees ( |
| Find declarations by words in their names, paths or documentation. |
| Every usage of a declaration, compiled from current source. |
| What the uncommitted changes (or those since |
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 JSONFAQ
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
Available Tools
4 toolsproject_check_changesWhat uncommitted changes affect (LayerMap)ARead-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)ARead-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)ARead-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)ARead-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
Scored across 4 tools
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.
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.
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.
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
Related MCP Connectors
Code intelligence platform for AI agents. 20 tools for architecture, security & impact analysis.
Codebase intelligence for AI agents — dead code, blast radius, ownership.
Deterministic context layer for your codebase: change impact, blast radius, answers with receipts.
Code intelligence for coding agents: semantic, AST, graph, and full-text search. 279+ languages.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables 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 PyPI4MIT
- AlicenseNot gradedqualityBmaintenanceEnables 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 npm2MIT
- AlicenseNot gradedqualityBmaintenanceEnables 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 PyPI1Functional Source , Version 1.1, ALv2 Future
- AlicenseBqualityBmaintenanceEnables 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.91MIT