stay-fresh-lsp-proxy

Stop stale LSP diagnostics from derailing your Claude Code sessions.

Note: This is a temporary workaround for issues with how Claude Code handles LSP diagnostics. Once the underlying problems are fixed upstream, this plugin will no longer be necessary. Relevant issues:

• LSP output displays stale diagnostics after file changes (#17979)
• pyright-lsp plugin promotes hint-level DiagnosticTag.Unnecessary into conversation context (#26634)
• TypeScript LSP plugin scans file paths in user prompt text, injecting unwanted diagnostics (#28562)

The Problem

Claude Code's LSP plugins fire textDocument/publishDiagnostics after every edit. The diagnostics arrive from the previous state of the file — not the current one. Claude sees these stale errors, thinks the code is broken, and tries to "fix" problems that don't exist. This leads to:

• Unnecessary reverts — Claude undoes correct work because a stale diagnostic says there's an error
• Fix loops — Claude chases phantom type errors that would resolve on their own after the next save
• Wasted turns — every edit triggers a round of outdated warnings that Claude has to reason about

The root cause is a timing issue: diagnostics lag behind edits, so Claude is always reacting to the previous state of your code.

How It Works

stay-fresh-lsp-proxy sits between Claude Code and your LSP server. It forwards everything normally (go-to-definition, hover, references, completions) but intercepts textDocument/publishDiagnostics notifications and filters them before they reach Claude. No stale diagnostics, no confused AI.

Quick Install

npx stay-fresh-lsp-proxy setup --typescript --python --rust

Pick only the languages you need:

npx stay-fresh-lsp-proxy setup --typescript              # Just TypeScript/JS
npx stay-fresh-lsp-proxy setup --typescript --python     # TypeScript + Python
npx stay-fresh-lsp-proxy setup --rust                    # Just Rust

This will:

1. Register the plugin marketplace with Claude Code
2. Install per-language plugins and disable conflicting official LSP plugins
3. Enable the LSP tool in Claude Code settings

Supported Languages

| Language | LSP Server | Install the server | |----------|-----------|-------------------| | TypeScript/JS | typescript-language-server | npm i -g typescript-language-server typescript | | Python | pyright-langserver | npm i -g pyright | | Rust | rust-analyzer | rustup component add rust-analyzer |

The setup script will warn you if the required LSP server binary is not found in your PATH.

Configuration

Control filtering behavior with environment variables. Set them in ~/.claude/settings.json under env:

{
  "env": {
    "STAY_FRESH_DROP_DIAGNOSTICS": "true",
    "STAY_FRESH_MIN_SEVERITY": "1",
    "STAY_FRESH_LOG": "false"
  }
}

Configuration Reference

| Variable | Default | Description | |----------|---------|-------------| | STAY_FRESH_DROP_DIAGNOSTICS | true | Drop all diagnostics. Set to false to use severity filtering instead. | | STAY_FRESH_MIN_SEVERITY | 1 | When not dropping all, the maximum severity level to keep. 1 = only errors, 2 = errors + warnings, 3 = errors + warnings + info, 4 = everything (same as no filter). | | STAY_FRESH_LOG | false | Enable debug logging to $TMPDIR/stay-fresh-lsp-proxy/. |

Recipes

Drop everything (default) — The nuclear option. Eliminates all stale diagnostics completely. Claude keeps full LSP intelligence (go-to-definition, hover, etc.) but never gets misleading error reports mid-edit.

{
  "env": {
    "STAY_FRESH_DROP_DIAGNOSTICS": "true"
  }
}

Errors only — Let genuine errors through (type mismatches, missing imports, syntax errors) but suppress warnings, hints, and info. Good if you want Claude to catch real breakage while ignoring the noise.

{
  "env": {
    "STAY_FRESH_DROP_DIAGNOSTICS": "false",
    "STAY_FRESH_MIN_SEVERITY": "1"
  }
}

Errors + Warnings — Also keep warnings (unused variables, deprecated APIs) but drop hints and info. You'll still get some stale notifications, but you're trading that off against Claude occasionally catching real issues it wouldn't otherwise notice.

{
  "env": {
    "STAY_FRESH_DROP_DIAGNOSTICS": "false",
    "STAY_FRESH_MIN_SEVERITY": "2"
  }
}

Everything except hints — Only drop hint-level diagnostics (like pyright's "unnecessary" markers that prompted #26634). Closest to stock behavior with the worst offenders removed.

{
  "env": {
    "STAY_FRESH_DROP_DIAGNOSTICS": "false",
    "STAY_FRESH_MIN_SEVERITY": "3"
  }
}

Debug mode — Combine with any of the above. Logs every intercepted diagnostic to $TMPDIR/stay-fresh-lsp-proxy/ so you can verify the proxy is running and see exactly what it's dropping.

{
  "env": {
    "STAY_FRESH_LOG": "true"
  }
}

LSP Severity Levels

| Level | Meaning | Examples | |-------|---------|---------| | 1 — Error | Code is broken | Type errors, missing imports, syntax errors | | 2 — Warning | Likely problems | Unused variables, deprecated API usage | | 3 — Info | Informational | Suggested refactors, style improvements | | 4 — Hint | Subtle suggestions | Unnecessary casts, removable parentheses |

Manual Install

If you prefer to set things up manually instead of using the setup script:

1. Add the marketplace:

   claude plugin marketplace add iloom-ai/stay-fresh-lsp-proxy

2. Install the plugin(s) you want:

   claude plugin install stay-fresh-typescript@stay-fresh-lsp-proxy
   claude plugin install stay-fresh-python@stay-fresh-lsp-proxy
   claude plugin install stay-fresh-rust@stay-fresh-lsp-proxy

3. Disable conflicting official plugins:

   claude plugin disable typescript-lsp@claude-plugins-official
   claude plugin disable pyright-lsp@claude-plugins-official
   claude plugin disable rust-analyzer-lsp@claude-plugins-official

4. Enable the LSP tool in ~/.claude/settings.json:

   {
     "env": {
       "ENABLE_LSP_TOOL": "1"
     }
   }

5. Restart Claude Code.

Uninstall

npx stay-fresh-lsp-proxy setup --uninstall

This removes all stay-fresh plugins and the marketplace registration.

Built by iloom

iloom is an AI development control plane for Claude Code. Decompose work into issues, swarm parallel agents across a dependency graph, and ship with full reasoning trails for every decision. Free to use — just bring your Claude Code subscription.

CLI | VS Code Extension

License

MIT