scale-lsp

A Claude Code plugin that wires up the SCALE clangd language server for CUDA source files.

With this plugin installed, Claude Code gets semantic understanding of .cu and .cuh files — go-to-definition, find-references, hover, and, uniquely, diagnostics inside inline asm("...") PTX blocks. Stock clangd treats inline PTX as opaque strings; SCALE clangd parses them and reports errors with accurate source locations.

Why this exists

LLM coding agents benefit enormously from LSP feedback: every edit produces a diagnostic signal, and the agent learns to fix the code rather than shipping broken attempts. For CUDA, that feedback loop has historically been half-missing — host-side C++ was diagnosed, device-side CUDA was roughly diagnosed, and inline PTX was a black box. SCALE's clangd closes that last gap, which matters when the agent is doing low-level kernel optimization where PTX is the actual optimization surface.

Prerequisites

• Claude Code 2.0.74 or later. LSP support is built in.
• SCALE toolkit installed, with clangd on your PATH. Get it from https://scale-lang.com.
• A supported GPU (NVIDIA or AMD — see the SCALE docs for the current compatibility matrix).

Verify your install:

clangd --version

Installation

From any directory:

claude /plugin marketplace add spectral-compute/scale-lsp
claude /plugin install scale-lsp@spectral-compute

Restart Claude Code. Confirm the plugin is active:

claude /plugin list

You should see scale-lsp@spectral-compute enabled.

Project Setup

The plugin tells Claude Code which language server to use for CUDA files. It does not tell clangd how to compile them — that's project-specific. For each project, drop a .clangd file at the root. A working template lives in examples/clangd.

Minimal example:

CompileFlags:
  Compiler: nvcc
  Add:
    - -xcuda
    - --cuda-path=/opt/scale
    - --cuda-gpu-arch=gfx942
    - --std=c++17
    - -ferror-limit=0
  Remove:
    - -gencode*
    - --generate-code*
    - -forward-unknown-to-host-compiler
    - -Xcompiler*
    - -Xfatbin*
    - -Xptxas*

See examples/README.md for a walkthrough.

Verification

Once installed and configured for a project, confirm all three of:

1. LSP reachable. Ask Claude: "Use the LSP to show the hover info for cudaMemcpy in this file." You should get a semantic response, not a grep.

2. .cu files are routed. Ask Claude to list symbols in any .cu file. If you get "no LSP server available for file type: .cu", the extension mapping didn't stick — see Troubleshooting.

3. PTX diagnostics work. Temporarily add this to a device function:

   int x = 0, y = 1;
   asm volatile("not_a_real_ptx_op.u32 %0, %1;" : "=r"(x) : "r"(y));

   Ask Claude to run LSP diagnostics on the file. You should see an error from SCALE clangd identifying the invalid mnemonic, with a source location pointing inside the asm string. Revert the bogus line once confirmed.

If #3 passes, you've got the full setup working.

Customisation

If scale-clangd isn't on your PATH, or you want to pass additional flags, override the command in your user settings. The plugin ships with these defaults:

{
  "command": "clangd",
  "args": [
    "--background-index",
    "--header-insertion=never",
    "--clang-tidy=false",
    "--query-driver=**",
    "--log=error"
  ]
}

--query-driver=** is intentionally permissive — it allows clangd to invoke any compiler in CompileFlags.Compiler to extract builtin defines. Narrow it (e.g. --query-driver=/opt/scale/bin/*) if you need tighter sandboxing.

Troubleshooting

No LSP server available for file type: .cu

The lspServers config didn't propagate from the plugin cache. Tracked upstream as anthropics/claude-code#14803. Workaround: reinstall the plugin (/plugin uninstall then /plugin install), and check that ~/.claude/plugins/cache/spectral-compute/scale-lsp/<version>/.lsp.json exists after install. If it doesn't, the cache population failed — file an issue here and we'll help diagnose.

clangd can't find CUDA headers

--cuda-path or --query-driver isn't resolving. Run SCALE clangd directly against your file:

clangd --check=path/to/your_file.cu

The output will flag missing includes or bad flags. Fix them in your project's .clangd.

PTX diagnostics don't appear

Source-location reporting inside PTX asm blocks requires SCALE 1.4 or later. Check scale-clangd --version and upgrade if needed.

Stock clangd is intercepting .cu files

If you have mainline clangd installed alongside SCALE clangd, and both are in PATH, they may race. Confirm only SCALE clangd is running:

ps aux | grep clangd

If stock clangd is also running, either remove it or explicitly set the command path in your user plugin overrides.

Contributing

Issues and PRs welcome at https://github.com/spectral-compute/scale-lsp.

License

MIT — see LICENSE.

SCALE itself (the compiler and runtime this plugin integrates with) is proprietary; see https://scale-lang.com for licensing terms on the SCALE toolkit.