metal-lsp

Metal LSP

Full language server features for Metal Shading Language in VSCode, Cursor, and Claude Code.

Autocomplete, inline diagnostics, hover documentation, and go-to-definition for .metal files. Powered by clangd with Metal-aware headers.

Features

Feature	macOS	Linux/Windows
Autocomplete (stdlib + user code)	Full (real SDK headers)	Full (stubs)
Inline diagnostics	Full	Best-effort (C++ mode)
Hover documentation	From MSL spec	From MSL spec
Go-to-definition	Yes	Yes (into stubs)
Syntax highlighting	TextMate + semantic	TextMate + semantic
Compile-on-save diagnostics	Yes (opt-in, via xcrun metal)	No

Requirements

• clangd — install via the clangd extension, Homebrew (brew install llvm), or your system package manager
• macOS (optional): Xcode or Command Line Tools for real Metal SDK headers. Without them, the extension falls back to bundled stubs.

Installation

VS Code / Cursor

Install from the VS Code Marketplace. The extension activates automatically when your workspace contains .metal files.

Also available on Open VSX for VSCodium and other editors.

Claude Code

/plugin marketplace add rayanht/metal-lsp
/plugin install metal-lsp@rayanht-metal-lsp

Or for local development: claude --plugin-dir /path/to/metal-lsp

Provides clangd-powered diagnostics, hover docs, and go-to-definition for .metal files directly in Claude Code CLI sessions. Requires clangd in PATH.

How It Works

The extension configures clangd to understand Metal by:

1. Registering .metal files as the "Metal" language
2. Running its own clangd language client scoped to Metal files
3. Generating a .clangd config that tells clangd to parse .metal as C++ with Metal-compatible flags
4. Providing a compat header that maps Metal keywords (device, constant, kernel, etc.) to C++ type qualifiers
5. Bundling stub headers so #include <metal_stdlib> resolves — on macOS with Xcode, real SDK headers are used instead

Settings

Setting	Default	Description
metal-lsp.metalStdVersion	"metal3.0"	Metal Shading Language standard version (metal1.0 through metal4.0) for compile-on-save
metal-lsp.compileDiagnostics	"off"	"off" or "onSave" — run xcrun metal for real compiler diagnostics (macOS only)
metal-lsp.includePaths	[]	Additional include directories for Metal shader compilation (added as -isystem paths)
metal-lsp.compileFlags	[]	Additional compile flags passed to both clangd and the Metal compiler

The workspace root is automatically added as an include path, so #include "shared/types.h" works out of the box if shared/ is at your project root. The includePaths setting is only needed for directories outside your workspace.

Commands

• Metal LSP: Configure — regenerate .clangd configuration
• Metal LSP: Show Status — show diagnostic info (header source, SDK path, configured folders)
• Metal LSP: Restart Language Server — restart the clangd language client
• Metal LSP: Open Documentation — open Apple's MSL spec

License

MIT