claude-code-lsp-enforcement-kit

In Action

When Claude tries to Grep for a code symbol, the hook blocks with a copy-pasteable LSP command:

⛔ LSP-FIRST BLOCK: Pattern contains code symbol(s) — use LSP instead
Symbols: handleSubmit, UserService

LSP tools:
  handleSubmit:
    mcp__cclsp__find_references("handleSubmit")  (cclsp)

  UserService:
    mcp__cclsp__find_workspace_symbols("UserService")  (cclsp)

When Claude tries to Read a code file without warming up LSP, the progressive gate blocks:

🛡️  LSP-FIRST READ GATE — Gate 1: warmup required

  Call one of these first:
    mcp__cclsp__get_diagnostics("src/page.tsx")  (cclsp)

  CONCRETE CALL FOR THIS FILE (works in any project):
    mcp__cclsp__get_diagnostics("src/page.tsx")

  After warmup: 2 free Reads, then need LSP navigation.

No generic advice. Every block message is parametrized by the actual file Claude tried to touch.

⚡ Quick Start

git clone https://github.com/nesaminua/claude-code-lsp-enforcement-kit.git
cd claude-code-lsp-enforcement-kit
bash install.sh
# Windows: pwsh ./install.ps1

Restart Claude Code. Done. The installer is idempotent — safe to re-run on upgrades.

Verify:

bash scripts/lsp-status.sh

🎯 The Problem

Claude Code defaults to Grep + Read for code navigation. This works, but it's wasteful:

"Where is handleSubmit defined?"

Grep approach:
  Grep("handleSubmit") → 23 matches, ~1500 tokens of output
  Read file1.tsx (wrong) → 2500 tokens
  Read file2.tsx (still wrong) → 2500 tokens
  Read file3.tsx (found it) → 2500 tokens
  ─────────────────────────────────────
  Total: ~9,000 tokens, 4 tool calls

LSP approach:
  find_definition("handleSubmit") → form-actions.ts:42, ~80 tokens
  Read form-actions.ts:35-55 → ~150 tokens
  ─────────────────────────────────────
  Total: ~230 tokens, 2 tool calls

~40x fewer tokens. Same answer.

A rule in CLAUDE.md saying "use LSP" helps ~60% of the time. Hooks make it 100%.

💰 Token Savings: Grep vs LSP Per Operation

📊 Real-World Data: 1 Week, 2 Projects

Aggregate from a week of development across 2 TypeScript projects:

How the estimate works:

• Each blocked Grep saves ~1200 tokens of noisy output
• Each avoided Read saves ~1500 tokens of file content loaded into context
• 39 LSP calls cost ~4k tokens total (precise, compact results)
• Without LSP: ~120 Greps + ~180 Reads = ~315k tokens for the same navigation work
• With LSP: 39 nav calls + 53 targeted Reads = ~84k tokens

🔌 Works with any LSP MCP server

v2.1 introduces provider-aware block messages. The kit detects which LSP MCP server(s) you have installed and tailors its suggestions accordingly:

• cclsp — standalone MCP server or bundled via the typescript-lsp Claude Code plugin. Suggestions use mcp__cclsp__find_definition, find_references, find_workspace_symbols, etc.
• Serena — high-level symbol MCP server (MIT, by Oraios AI). Multi-language support (Python, Go, Rust, Java, TypeScript, Vue, and more via its bundled solidlsp wrapper). Suggestions use mcp__serena__find_symbol, find_referencing_symbols, get_symbols_overview.
• Both installed — suggestions show entries for both providers.
• Neither installed — generic fallback with install hints for both.

Detection reads user-level Claude Code config (~/.claude.json, ~/.claude/settings.json) and matches known server names. The shared helper is in hooks/lib/detect-lsp-provider.js — adding a new provider means adding one entry to its PROVIDERS registry, with no changes to the individual hooks.

🏗️ Architecture: 6 Hooks + 1 Tracker

                    PreToolUse                          PostToolUse
                    ──────────                          ───────────

 Grep call ──→ [lsp-first-guard.js] ──→ BLOCK
                  detects code symbols,
                  suggests LSP equivalent

 Glob call ──→ [lsp-first-glob-guard.js] ──→ BLOCK
                  blocks *UserService*, **/handleFoo*.ts;
                  allows *.ts, *subdomain*, src/**

 Bash(grep) ──→ [bash-grep-block.js] ──→ BLOCK
                  catches grep/rg/ag/ack
                  in shell commands

 Read(.tsx) ──→ [lsp-first-read-guard.js] ──→ GATE
                  5 progressive gates
                  (warmup → orient → nav → surgical)

 Agent(impl) ─→ [lsp-pre-delegation.js] ──→ BLOCK
                  subagents can't access MCP,
                  orchestrator must pre-resolve

 LSP call ─────────────────────────────────────→ [lsp-usage-tracker.js]
                                                   tracks nav_count,
                                                   read_count, state

                    SessionStart
                    ────────────

 New session ──→ [lsp-session-reset.js] ──→ WIPE
                    clears stale nav_count for current cwd,
                    forces fresh warmup + re-enforces gates

v2 note: versions before v2 had two silent bypass routes that let Claude read code files without ever calling LSP: (1) Glob("*SymbolName*") had no guard, and (2) nav_count persisted for 24 h across sessions, so a new session inherited "surgical mode" (unlimited reads) from yesterday's LSP work. Both are closed in v2 by lsp-first-glob-guard.js and lsp-session-reset.js. If you installed v1, re-run bash install.sh — it merges the new hooks without touching your existing settings.

🔧 How Each Hook Works

1. lsp-first-guard.js — Grep Blocker

Hook type: PreToolUse | Matcher: Grep

Intercepts every Grep call. Detects code symbols in the pattern. Blocks with a suggestion to use the correct LSP tool.

Block message example (with both cclsp and Serena detected):

⛔ LSP-FIRST BLOCK: 1 code symbol(s) in Grep — use LSP instead
Symbols: handleSubmit
LSP tools:
  handleSubmit:
    mcp__cclsp__find_references("handleSubmit")  (cclsp)
    mcp__serena__find_referencing_symbols("handleSubmit")  (Serena)

If only one provider is installed, only that suggestion appears.

2. lsp-first-glob-guard.js — Glob Symbol Blocker

Hook type: PreToolUse | Matcher: Glob

Closes the gap where Claude searches for a symbol by filename pattern instead of content. Without this hook, Glob("*UserService*") silently returns the file, Claude reads it, and LSP enforcement never fires.

The guard parses the glob pattern, extracts alphabetic tokens, and blocks if any token looks like a code symbol (PascalCase, camelCase, or snake_case with 3+ pa