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:
- Registering
.metal files as the "Metal" language
- Running its own clangd language client scoped to Metal files
- Generating a
.clangd config that tells clangd to parse .metal as C++ with Metal-compatible flags
- Providing a compat header that maps Metal keywords (
device, constant, kernel, etc.) to C++ type qualifiers
- 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
