The way Claude Code handles code navigation by default leans heavily on Grep and Read tool calls, which can quickly balloon token usage and slow down your AI agent. claude-code-lsp-enforcement-kit steps in to intercept these tool calls using hooks and enforce a more efficient LSP-first approach. The result is a system that cuts token waste by roughly 73% in real-world usage, turning a soft guideline into hard enforcement with measurable savings.
What claude-code-lsp-enforcement-kit does and how it works
At its core, this project is a hook-based enforcement kit designed for Claude Code. It intercepts calls to code navigation tools like Grep, Glob, Bash (grep), and Read, and instead routes navigation queries through LSP (Language Server Protocol) MCP servers such as cclsp or Serena.
The main architectural pattern involves six PreToolUse and PostToolUse hooks that monitor and control the usage of these tools during a Claude Code session. A session tracker maintains state about the navigation context and enforces progressive read gating — a staged approach to refining navigation intensity through phases: warmup, orient, nav, and surgical. This gating system helps escalate from broad exploratory reads to precise, surgical reads as needed.
Provider detection reads the Claude Code configuration to identify which LSP MCP servers are available, generating provider-aware block messages and copy-pasteable LSP commands to guide the user.
Under the hood, this means the system blocks token-heavy and noisy Grep+Read patterns that typically produce large and wasteful outputs. Instead, it forces Claude Code to make targeted LSP calls that return much smaller, more precise results aligned with code symbols and definitions.
The repo is written in JavaScript and integrates tightly with Claude Code’s plugin and hook system. It works out-of-the-box with a simple installation script that sets up the hooks and restarts Claude Code.
Why the enforcement kit matters
The token savings are concrete and impressive. Real-world data from two TypeScript projects shows about a 73% token reduction (~235k tokens saved over a week) when switching from Grep+Read to LSP navigation enforced by these hooks.
Here are some detailed benchmarks from the README:
| Task | Grep+Read tokens | LSP tokens | Savings |
|---|---|---|---|
Find definition of handleSubmit | ~6500 | ~580 | 91% |
Find all usages of UserService | ~1500 | ~150 | 90% |
Check type of formData | ~2500 | ~60 | 98% |
Find component InviteForm | ~3500 | ~100 | 97% |
Who calls validateToken | ~7500 | ~700 | 91% |
This translates into roughly 40x fewer tokens for the same answers, which directly impacts cost and performance when you rely on Claude Code for code navigation and understanding.
The progressive read gating mechanism is a practical innovation here. Instead of outright blocking all Grep+Read calls, it stages the navigation process to gradually refine reads, allowing warmup and orientation phases before moving to surgical reads. This balances precision with the flexibility needed for exploration.
The provider-aware messages improve developer experience by detecting installed MCP servers and suggesting exact LSP commands to run. This also helps make the enforcement less intrusive and more transparent.
Tradeoffs are mostly about complexity and dependency on LSP MCP servers. If the MCP servers are not properly configured or unavailable, the enforcement might block too aggressively or degrade DX. Also, the solution is tightly coupled to Claude Code’s plugin and hook system, so it’s not a drop-in for other AI coding assistants without similar extension points.
Quick start with claude-code-lsp-enforcement-kit
Getting started is straightforward. From the repo’s root:
git clone https://github.com/nesaminua/claude-code-lsp-enforcement-kit.git
cd claude-code-lsp-enforcement-kit
bash install.sh
# Windows users can run:
pwsh ./install.ps1
After installation, restart Claude Code to activate the hooks.
To verify the setup and status of the LSP integration, run:
bash scripts/lsp-status.sh
This script helps confirm the MCP server connectivity and the active enforcement of LSP-first navigation.
verdict: who should consider using this kit
If you use Claude Code for AI-assisted code navigation and regularly deal with token-heavy, noisy Grep+Read queries, this enforcement kit is worth trying. It directly addresses token bloat and improves the efficiency of code symbol lookups by redirecting to precise LSP MCP servers.
The solution shines in TypeScript and similar language projects where LSP servers are mature and reliable. It enforces best practices automatically, which is a big DX win for teams that want consistent LSP-first navigation without relying on manually following CLAUDE.md guidelines.
However, this is not a silver bullet. The dependency on MCP servers means you need a functional LSP backend setup. Also, the enforcement hooks add complexity and may not fit all workflows, especially if you rely on Grep for certain edge cases or have atypical codebases.
Overall, claude-code-lsp-enforcement-kit is a pragmatic, well-engineered tool that solves a real pain point for Claude Code users. Its progressive gating and provider-aware messaging stand out as thoughtful design choices. Worth a spin if you want to optimize your Claude Code navigation and cut token waste substantially.
→ GitHub Repo: nesaminua/claude-code-lsp-enforcement-kit ⭐ 277 · JavaScript