LayerMap MCP server

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}".

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

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.