vscode-clangd is a thin bridge to the clangd language server, and the compile flags are yours to supply

The extension is a transport layer, the server is the product

It helps to be clear about which piece does the work. vscode-clangd is a Visual Studio Code extension written in TypeScript, and its job is to run the clangd language server and relay messages between it and the editor. The repository description says exactly that: a Visual Studio Code extension for clangd, published under the llvm-vs-code-extensions publisher with the display name clangd.

The capabilities the README lists all come from the server: code completion, compile errors and warnings, go-to-definition and cross references, hover information and inlay hints, include management, code formatting and simple refactorings. The extension does not parse C++ and it does not implement diagnostics. If you want to know how any of these behave, the answer lives in the clangd documentation at clangd.llvm.org, not in this repository.

That split has a practical consequence for the repository itself. The top level entries show a small project: src, test, types, api, docs, a .clang-format file, a CHANGELOG.md and a DEVELOPING.md. The build is a single esbuild invocation that bundles src/extension.ts into out/bundle.js, and the package manifest points at that bundle as the main entry.

    "main": "./out/bundle",
    "engines": {
        "vscode": "^1.91.0"
    },

The activation list covers the language identifiers the extension claims, which tells you the scope of what it will try to serve.

    "activationEvents": [
        "onLanguage:c",
        "onLanguage:cpp",
        "onLanguage:cuda-cpp",
        "onLanguage:objective-c",
        "onLanguage:objective-cpp"
    ],

Getting clangd onto the machine

The extension requires the clangd language server, and the setup section is short because there is not much to decide. If the server is not found on your PATH, the extension prompts you to download it. Automatic installation is possible on x86-64 Linux, Windows and Mac, so the common developer laptop is covered without a package manager.

If you already have an older clangd on the system, the extension gives you a way to deal with it: a command palette entry called Check for clangd language server update.

That split between automatic download and system install is worth thinking about, because it decides where your clangd version comes from. A server you downloaded through the extension and a server from your distribution package can be different versions, and the behaviour of index and diagnostic behaviour can differ between them. If you want a pinned version, install it yourself and make sure it is the one on PATH.

The extension also carries a .clang-format file at the repository root and a format script that runs clang-format over the TypeScript sources, which is a detail of the extension's own development rather than of your C++ project, but it does indicate that the project follows the LLVM formatting conventions.

compile_commands.json is the part people get wrong

Here is the constraint that decides whether this extension is usable for you.

clangd is based on the clang C++ compiler and understands even complex C++ code, but you must tell clangd how your project is built, meaning you must supply the compile flags. The README says a compile_commands.json file can usually be generated by your build system, and it gives CMake as the example, where setting the following flag makes the build emit the file.

The flag itself is `-DCMAKE_EXPORT_COMPILE_COMMANDS=1`, passed to the configure step of your build.

Without that file, clangd is guessing, and a guess on a C++ codebase with headers, macros, platform defines and conditional compilation produces errors that are not in your code. The symptoms are well known to anyone who has tried it: red squiggles under perfectly valid headers, unresolved includes, and completions that omit symbols from conditionally compiled code.

The README links to the Project Setup section of the clangd documentation for details and alternatives, which is the right next step if your build system is not CMake. The general shape of the problem is the same for any build system: something has to emit the exact command line used to compile each translation unit, and that is what the JSON compilation database stores.

There is a second configuration surface as well. The server supports a number of feature customisations through its own config file, and the README links it. In practice, the extension gives you the features and clangd's config file is where you tune them.

What the editor features actually give you

The feature list in the README is specific enough to be worth unpacking.

Completion uses a full C++ parser, so suggestions have access to precise type information and appear as you type names or after a dot or arrow. Diagnostics are shown both as red squiggles and in the Problems panel, and the README notes they are the same as those produced by the clang compiler, with suggested fixes that can be applied automatically. Most clang-tidy checks are supported, enabled through a .clang-tidy file in the project.

Cross references and go-to-definition work across the codebase using a project-wide index, and Ctrl-P followed by the hash sign navigates to a symbol by name. Hover describes almost any entity, with the keyboard shortcut given as Ctrl-KI. Inlay hints for parameters and deduced types can be shown temporarily or permanently, controlled by the editor.inlayHints.enabled setting.

Include management is the feature that saves the most typing in practice. clangd suggests inserting missing includes where they cause errors, adds include directives as part of completion, and can warn on unused includes.

Formatting uses the clang-format engine, and when Format on Type is enabled, pressing enter causes clangd to format the old line and semantically reindent. The style comes from the project .clang-format file. If you would rather use another formatter, the README points at the editor.defaultFormatter setting as the way to override it.

Refactorings are local ones, offered in the lightbulb menu when you select an expression or declaration: extract variable or function, expand auto types and macros, use raw strings, and rename. Rename is the odd one out because it is bound to F2 rather than being a contextual code action.

Where this extension is the wrong choice

The first wrong-tool case is a build system that will not produce a compile_commands.json. Not every project can emit one without effort, and a project built by a bespoke script or a non-standard toolchain may need work before clangd can see it. In that situation the extension installs cleanly and then reports errors that belong to the missing configuration, which is a bad first impression and a common source of abandoned setups.

The second is a project that is not C or C++. The activation list covers c, cpp, cuda-cpp, objective-c and objective-cpp, and the README's feature descriptions are all about the clang C++ front end. There is no path here for Rust, Go, TypeScript or Python, and there never will be in this extension.

The third is an expectation that the extension replaces clangd. It does not. All configuration beyond the basics lives in the clangd config file and the project's own .clang-format and .clang-tidy files, and the full clangd documentation is the reference for what the server can do. If you install this extension expecting a self-contained C++ IDE experience, you will spend your time reading clangd documentation instead.

A fourth, smaller limitation: automatic server installation covers x86-64 Linux, Windows and Mac. Other architectures, and environments where the editor has no network access to fetch the server, need a manually installed clangd on PATH.

Releases, licence and where the code lives

The repository is not archived and the last push was on 2026-10-22. The release history shows 0.4.0 on 2026-01-20, 0.5.0 on 2026-05-09 and 0.6.0 on 2026-05-21, and the package version in the manifest matches the newest of those.

The 0.x version number is a signal worth reading carefully, since it means the extension has not yet declared a stable 1.0 API and can still make breaking changes in a minor release. The README itself contains no compatibility promise for the extension, only the guarantees documented on the clangd side.

The licence is MIT, stated in the LICENSE file at the root and in the package manifest. The publisher is llvm-vs-code-extensions and the extension is part of the LLVM project, with the clangd server itself part of the LLVM project with issues filed in the clangd/clangd repository.

Two different issue trackers, which the README spells out, are worth remembering. A bug in the extension belongs in the vscode-clangd tracker, and a bug in the language server belongs in the clangd tracker. If you are unsure which one to file against, the difference matters, because a server bug fixed upstream will not be delivered to you by updating the extension. The project also points at the clangd-dev mailing list for anyone who wants to help.

Development instructions live in DEVELOPING.md, and the build scripts give a picture of the toolchain.

        "esbuild": "esbuild ./src/extension.ts --bundle --outfile=out/bundle.js --external:@aws-sdk/client-s3 --external:vscode --format=cjs --platform=node",
        "check-ts": "tsc -noEmit -p ./",
        "test": "npm run test-compile && node ./out/test/index.js",

Publishing goes out to both the Microsoft marketplace and Open VSX, with a separate pre-release packaging script for each.

Editorial conclusion

vscode-clangd fits C and C++ teams on Visual Studio Code whose build system can emit a compile_commands.json, and it is the right choice for anyone who wants clang-tidy checks and clang-format behaviour in the editor rather than only in CI. It does not fit a project whose build cannot export compile commands without significant work, and it does not replace clangd itself, since the language server does all the parsing. Before adopting, generate the compilation database and confirm clangd indexes the project correctly without the extension, install the server and let the extension prompt you for it if it is missing from PATH, and read the clangd config file documentation, since most behaviour beyond the basic feature set is configured there rather than in the extension.

Frequently asked questions

Official sources

1. clangd/vscode-clangd on GitHub
2. License: MIT
3. Project website
4. README
5. Releases