On this page · 10 sections
- Why I went looking
- Why bother with LSP?
- Why "just turn it on" wasn't enough
- Measure first: a headless benchmark
- Debugging the wrong layer, five times
- What the PHP LSP benchmark showed
- The alternative: an Adobe Commerce-aware MCP server
- Instructions didn't change behaviour. Hooks did.
- Caveats, stated plainly
- What I'd tell another Adobe Commerce team
TL;DR
- Claude Code's LSP tool runs
git check-ignoreon every navigation result and silently drops anything gitignored. On an Adobe Commerce (Magento 2) project, that'svendor/at minimum. On one client project, it was everything. - The error you see, "not fully indexed", points at the wrong layer. Run
git check-ignoreon the file before you debug indexing. - For Adobe Commerce wiring questions (plugins, observers, DI), the
magento2-lspMCP server answered every question correctly where Grep got most of them right, with more than five times fewer tool calls at about two fifths lower cost. - Instructions in CLAUDE.md didn't change Claude's tool choice. A hook did.
Zero. That's how many times Claude Code had called its LSP tool across about eighty saved sessions on one of my projects, a large Adobe Commerce Cloud marketplace build: a Mirakl connector and more than twenty custom modules installed through Composer into vendor/<client>/. intelephense was installed. The TypeScript server wasn't. Every "who calls this method?" question had been answered by Grep, file by file.
Why I went looking
This didn't start as a tooling experiment. It started with three problems that kept recurring on that project.
Navigation was slow. Questions any Adobe Commerce developer answers in their IDE in seconds, like "who calls this?" or "which class implements this interface?", took Claude a long chain of searches and file reads. On a codebase this size, I'd regularly sit watching it grep its way through vendor/ for something my IDE would find with one click.
Answers were sometimes wrong, or quietly incomplete. A grep that misses one caller doesn't fail. It returns a confident, partial answer. More than once Claude told me it had found every place a method was used, or every plugin on a class, and I caught a missing one later. In a marketplace integration, a missed caller is the difference between a safe refactor and a broken order sync. (In the PHP navigation benchmark further down, Grep gets all ten answers right; those questions are small and direct. The misses came in real sessions, on bigger questions, and they show up again in the wiring benchmark.)
The one that stuck: Claude listed the plugins on an order-sync method and missed one declared in another module's di.xml. I found out when a refactor changed the method's signature and that plugin broke in testing.
It was expensive. Every grep hit that Claude has to check is another file read into context. Long navigation sessions burned through tokens, and on heavy days, through my usage limits, on work that wasn't the actual task.
In a typical navigation-heavy session, roughly half the tool calls were Grep and file reads just to find the code.
A language server should fix all three, because it answers navigation questions from an index instead of from text matches. When I checked, intelephense was already installed. The audit of those sessions explained the rest: Claude had never once called it.
Why bother with LSP?
Grep finds text. A language server finds meaning. For a coding agent, that difference shows up as a bill.
Ask Claude "who calls save() on this repository?" with only Grep, Glob and Read, and it has to work like a junior developer with grep -rn. It searches for the method name, gets every save( in the codebase, and opens file after file to check which class each call actually belongs to. Adobe Commerce makes this worse than most codebases. Method names like execute, save and getById repeat across thousands of classes. Calls go through interfaces resolved by di.xml. And vendor/ holds tens of thousands of PHP files to search through. Every false match costs a Read, and every Read lands in the context window.
A language server has already parsed the code. It knows types, inheritance and which class a variable holds, so it can answer the questions an agent asks most often with one precise call:
findReferences: real callers of this exact method on this exact class, not every method that happens to share the name.goToImplementation: the classes that implement an interface, without guessing from file names.hover: a symbol's type and return type, without reading the whole class.documentSymbol: a class's methods and properties as a list, without loading the file into context.
In theory, that means fewer tool calls, fewer tokens and fewer wrong answers caused by a missed or misread grep hit. The baseline numbers below show where the theory should pay off: finding a method's callers or its usages cost Claude well over ten tool calls, where a working language server needs one.
Why "just turn it on" wasn't enough
I turned LSP on properly. I followed the "Setting it up" steps in this guide to LSP in Claude Code, enabled the official php-lsp plugin, and added a "Code Intelligence: prefer LSP over Grep/Glob/Read" section to my global ~/.claude/CLAUDE.md. I skipped ENABLE_LSP_TOOL, because Claude Code 2.1.316 already ships the tool. Plugins are enabled per project in .claude/settings.local.json: php-lsp on the Adobe Commerce projects, typescript-lsp on the TypeScript ones.
Then I went back to work and watched. The plugin was on. The instruction was in CLAUDE.md. Claude still reached for Grep on almost every navigation question, and on the rare occasion it tried LSP, it got nothing back and grepped anyway. So I benchmarked it properly, and the first run showed no improvement at all.
That's when this stopped being a five-minute setup and became a debugging project. Either LSP doesn't help on Adobe Commerce, or my setup was broken. The numbers couldn't tell me which.
It took a couple of evenings. The turning point was running intelephense directly: it returned all twenty-odd references, and Claude Code showed none.
Measure first: a headless benchmark
Going by feel is how you convince yourself a tool helps. I wrote a small Python harness around headless Claude Code instead:
claude -p "$TASK" --output-format stream-json --verbose --max-turns 30 \
--allowedTools Read,Grep,Glob,LSP \
--disallowedTools Bash,Agent,Write,Edit,WebFetch,WebSearch \
--strict-mcp-config --mcp-config '{"mcpServers":{}}' \
--settings '{"enabledPlugins":{...}}' \
--append-system-prompt "$PREFER_LSP"
The script parses the stream for tool calls by tool, input tokens, cost and wall time, then checks each answer against a known-correct one. There are five PHP navigation tasks, each run twice per configuration: find a method's callers (T1), find an interface's implementing class (T2), find usages including a webapi.xml reference (T3), work out a return type (T4), and list a class's methods (T5).
The baseline, with LSP off, shows where Grep hurts:
| Task | Tool calls | Input tokens | Cost | Time |
|---|---|---|---|---|
| T1 callers | 15–20 (mostly Grep) | about 300k | about 20 cents | about 40 s |
| T2 implementer | a few | 100–150k | about 10 cents | 10–20 s |
| T3 usage incl. webapi.xml | about 20 | about 350k | about 20 cents | about 45 s |
| T4 return type | a few | about 150k | about 15 cents | about 50 s |
| T5 list methods | a few | about 150k | about 15 cents | about 15 s |
T1 and T3 are exactly the calls findReferences should replace.
Debugging the wrong layer, five times
1. The index was cold every session
The official plugin starts intelephense with nowhere to store its index. So every session re-indexed tens of thousands of PHP files in vendor/, which took about five minutes. My benchmark sessions last a minute at most. findReferences therefore always answered "LSP server has not fully indexed the workspace", and Claude fell back to Grep. Only documentSymbol, which reads a single file, worked.
I wrote a local plugin, php-lsp-magento, that gives intelephense a persistent index location:
"initializationOptions": {
"storagePath": "~/.cache/intelephense",
"globalStoragePath": "~/.cache/intelephense"
}
Reload time dropped from about five minutes to about twenty seconds, and later to about ten. A warm-up script pre-builds the index. A second Adobe Commerce project indexed tens of thousands of files in under five minutes, and the cache for the two projects comes to under 200 MB.
2. The server starts lazily
Claude Code starts the language server on the first LSP call in a session, not at session start. So the first lookup in every session comes back empty. That's annoying, but at least it's predictable.
3. Unclean shutdowns throw the index away
If an intelephense process isn't shut down cleanly, it discards the saved index and forces a full rebuild of about five minutes. Until that rebuild finishes, only hover and documentSymbol work.
4. Missing settings mean no indexing at all
This one's subtle. If the plugin's settings key is absent, Claude Code advertises workspace.configuration: false. If settings is {}, Claude Code answers intelephense's workspace/configuration request with [null, null]. Either way, intelephense never indexes the workspace. It only knows about open files, which explains why hover and documentSymbol worked while findReferences stayed empty.
The fix, in plugin v1.0.3, is a non-empty settings block that does nothing except restate a default:
"settings": {
"intelephense": { "files": { "maxSize": 1000000 } }
}
5. The real blocker: gitignored results are dropped
Even after all that, references were still empty. So I put a tee wrapper on intelephense's stdin and stdout, and read the raw protocol traffic. intelephense returned all twenty-odd references for the method under test. Inside the same Claude Code session, the LSP tool reported "No references found… not fully indexed".
The cause: Claude Code's LSP tool runs git check-ignore on every location returned by findReferences, goToDefinition, goToImplementation and workspaceSymbol, and silently drops any gitignored file. Setting respectGitignore: false in settings.json doesn't change it; the key isn't in the current settings docs either. hover, documentSymbol and diagnostics aren't filtered, which is why they kept working and kept me looking at indexing.
The marketplace project's .gitignore starts with *, a whitelist style. All of its custom code lives in vendor/<client>/*. Every navigation result was being thrown away before Claude saw it.
git check-ignore -v vendor/<vendor>/<module>/Model/SomeService.php
"Not fully indexed" was the server being blamed for a filter in the client. Check ignore rules before you touch indexing.
What the PHP LSP benchmark showed
| Run | Correct | Tool calls | LSP calls | Grep calls | Input tokens | Cost | Time |
|---|---|---|---|---|---|---|---|
| Baseline (LSP off) | all | about 10 | 0 | about 7 | about 210k | about 15 cents | about 30 s |
| LSP on, cold index | all | about 10 | under 1 | about 5 | about 240k | about 15 cents | about 30 s |
| LSP on, "warm" index | all | about 9 | under 1 | about 5 | about 220k | about 12 cents | about 25 s |
The differences between rows are run-to-run noise, because every navigation result was filtered out in all three. The cold run is the instructive one. The "prefer LSP" instruction cost about a seventh more input tokens, because Claude dutifully tried LSP, got nothing, and then grepped anyway. Without the benchmark, I'd have called that an improvement.
How much LSP navigation helps depends entirely on what git ignores:
| Project | vendor/ | app/code | LSP navigation |
|---|---|---|---|
| The marketplace project | ignored | ignored (.gitignore is *) | none |
| A few other Adobe Commerce projects | ignored | tracked | works inside app/code, misses calls into vendor/ |
So I turned PHP LSP off on the marketplace project and kept it on for the others. The global CLAUDE.md now says two things. A "No references found" for code under a gitignored path is unreliable, so switch to Grep immediately. And the first call after a lazy start may return only the declaration.
TypeScript doesn't have the problem
typescript-lsp works in my TypeScript projects, because their source is tracked in git. findReferences returned every reference in one project and a handful across a few files in another, matching Grep both times. There are two gotchas. tsserver needs about 7 seconds after the lazy start, and a findReferences inside that window returns only the declaration; Claude once read that as "no usages". And typescript-language-server must be on PATH when Claude starts. Mine was installed under nvm's Node 24, so Claude has to be launched from a shell where nvm is loaded.
The alternative: an Adobe Commerce-aware MCP server
The more useful realisation was that for Adobe Commerce, a PHP call graph is the wrong model anyway. Plugins, observers and DI preferences live in XML. "Who hooks into this?" isn't a find-references question.
magento2-lsp from Mage-OS (npm @mage-os/magento2-lsp 0.1.0, MIT, sponsored by Hyvä) ships two servers. Its LSP server has the same gitignore problem, so it's no use here. Its MCP server, magento2-lsp-mcp, works, because MCP tool results don't pass through the LSP tool's filter.
It exposes magento_get_di_config, magento_resolve_class, magento_get_plugins_for_method, magento_get_event_observers, magento_get_template_overrides, magento_get_class_hierarchy, magento_get_module_overview, magento_get_db_schema, magento_search_symbols, magento_get_class_context and magento_rescan_project. Each takes a filePath inside the project. It doesn't cover webapi.xml routes and ACL, or PHP "find callers".
A smoke test answered four questions in under half a minute, including session start. The index is cached at the project root in .magento2-lsp-cache.json, which is a few tens of MB.
The wiring benchmark: magento2-lsp MCP against Grep
I ran it on the same headless claude -p harness as the PHP benchmark. The baseline allowed Read, Grep and Glob. The MCP run added the server plus a one-line nudge to use magento_* tools first. There were five wiring questions, two runs each, with expected answers checked by hand against the XML and the PHP autoloader:
- M1: the DI preference for a service interface.
- M2: every observer on
sales_order_place_after(about half a dozen expected, across core and third-party modules). - M3: every plugin on
Magento\Quote\Model\Quote::addProduct, which needs method-level matching. - M4: the REST route and ACL resource for a service method.
- M5: every event a custom tax module observes.
| Run | Correct | Tool calls | Input tokens | Cost | Time |
|---|---|---|---|---|---|
| Grep/Read/Glob only | most | about 20 | about 280k | about 20 cents | about 40 s |
| + magento2-lsp MCP | all | about 4 | about 140k | about 12 cents | under 20 s |
That's more than five times fewer tool calls, about two fifths cheaper and about twice as fast, with every answer correct. Per question:
| Question | Baseline | With MCP |
|---|---|---|
| M1 DI preference | right in both runs, a handful of calls | right in both runs, a couple of calls |
| M2 observers on event | right in one of two runs; one run made over a hundred Grep/Glob calls, cost about 50 cents, took about two minutes, and still missed observers | right in both runs, a few calls, under 20 s |
| M3 plugins on method | wrong in both runs, about 30 calls each, missed plugins both times | right in both runs, a few calls, about 20 s |
| M4 webapi route and ACL | right in both runs | right in both runs; MCP not used (no webapi tool), no gain |
| M5 module's events | right in both runs | right in both runs, about the same cost |
The wins land exactly on "find everything that hooks into X" questions. Answering those by hand means scanning every di.xml and events.xml across hundreds of modules, then opening each plugin class to check which methods it actually intercepts. Grep does that expensively at best and incompletely at worst. The MCP server answers from a prebuilt index in one call. Where it has no tool, as with M4, it makes no difference.
Instructions didn't change behaviour. Hooks did.
Next I added magento2-lsp-mcp as a local MCP server in several Adobe Commerce projects. I put the cache file into .git/info/exclude where it wasn't already ignored. And I wrote a rule into the global and project CLAUDE.md: use magento_* tools first for DI, plugins, observers, templates, class hierarchy and db_schema, and Grep webapi.xml.
By 5 November Claude was still grepping events.xml and di.xml. The reason was mechanical. The MCP tools were deferred: Claude Code lists their names but needs a ToolSearch call to load their schemas. Against that extra step, Grep looked cheaper, so Grep won. A sentence in CLAUDE.md doesn't change that maths.
So I wrote a guard hook (bash, in global settings; a later one taught me to refuse, not rewrite) that's active only when the project root contains bin/magento:
| Hook | Effect |
|---|---|
| SessionStart (startup, resume, clear, compact) | Injects a reminder to use the magento_* tools, with the one-line ToolSearch command that loads them all |
| PreToolUse on Grep or Bash | Blocks searches targeting di.xml, events.xml, crontab.xml or db_schema.xml, and XML greps for <plugin, <preference or <observer, then names the right tool. webapi.xml, acl.xml, PHP code, git diff and Read on a known file stay allowed |
| PostToolUseFailure on any magento2-lsp tool | Unlocks Grep for the rest of that session |
There's also a manual escape: add # lsp-fallback: <reason> to the Bash command, and the reason stays visible in the transcript. I tested it live. A grep on events.xml was blocked, and the same grep with the marker went through.
grep -rn "sales_order_place_after" --include=events.xml vendor/ # lsp-fallback: checking a module the index skipped
A guard without an escape hatch is an outage waiting to happen. This one has two.
One line in my global CLAUDE.md also gives each session a papercuts log of what slowed it.
Caveats, stated plainly
magento2-lspis v0.1.0. One answer gave a plugin count that didn't match the plugins it listed, and the module overview shows plugin target classes as"unknown". Check counts before you act on them.- The sample is small: five tasks, two runs each. The direction is clear; the exact percentages aren't.
- I observed the gitignore filtering in Claude Code 2.1.316 and saw it again on 2.1.319. Later versions may behave differently, so run
git check-ignoreon your own setup before trusting either result.
What I'd tell another Adobe Commerce team
- When you see "not fully indexed", run
git check-ignore <file>before you debug indexing. The LSP tool drops gitignored results, and every Adobe Commerce project ignoresvendor/, so navigation can return nothing while the server works perfectly. - For intelephense under Claude Code, set a non-empty
settingsobject or it never indexes. PersiststoragePath, and expect the first call in a session to come back empty. - Benchmark with headless
claude -pand stream-json. My cold-index "improvement" was actually worse. - For framework wiring, a domain-aware MCP server beats a generic language server, because in Adobe Commerce the wiring lives in XML.
- Enforce tool choice with hooks, and give every hook two ways out: an automatic unlock when the tool fails, and a manual escape marker.
The setup around this is in Claude Code on WSL and my herdr setup.



