C++ Intelligence LSP

Preview release. Feedback from real-world CMake projects is welcome.

C++ Intelligence LSP is a high-accuracy C and C++ language extension for Visual Studio Code, powered by clangd. It uses Clang's parser, your real build commands, and a project-wide background index instead of a simplified C++ parser.

The extension is designed for projects where correctness across source files, headers, libraries, generated files, and external dependencies matters more than a minimal setup.

Highlights

• Completion, hover, diagnostics, rename, references, and navigation across .cpp, .h, and .hpp files
• Automatic discovery and validation of compile_commands.json
• Independent clangd process for each folder in a multi-root workspace
• Project-wide background indexing and clang-tidy diagnostics
• Detailed completion with clangd's Decision Forest ranking and up to 500 candidates by default
• Local frequency and recency ranking based on accepted completion items
• Dedicated completion inside empty #include <> and #include "" delimiters
• C++23 standard-header suggestions, plus project and external-library header indexing
• CMake FetchContent, vcpkg, generated-header, and explicit -I/-isystem include-root support
• Macro completion from build definitions and included headers
• Optional automatic header insertion with redundant transitive includes suppressed
• Automatic restart when the compilation database or .clangd configuration changes
• Built-in diagnostics for clangd, compilation databases, stale CMake configuration, and competing providers

Requirements

• Visual Studio Code 1.90 or newer
• LLVM clangd 18 or newer is recommended
• A C/C++ compiler and build system
• For the recommended workflow: CMake Tools and Ninja

Install clangd and either add it to PATH or configure cppIntelligence.clangdPath. On Windows, the extension also searches common LLVM, MSYS2, and Scoop locations.

Quick start

1. Install this extension.
2. Open the root folder of your CMake project.
3. Add the recommended settings below to .vscode/settings.json.
4. Run CMake: Select a Kit and choose an LLVM/Clang kit.
5. Run CMake: Configure.
6. Confirm that build-clangd/compile_commands.json exists.
7. Run C++ Intelligence: Restart Language Servers.

The first background index may take some time on a large project. clangd caches it for later sessions.

Recommended CMake Tools configuration

The following is a complete Windows configuration for CMake Tools, Ninja, LLVM, and this extension. Save it as .vscode/settings.json in the project root.

{
  "cmake.generator": "Ninja",
  "cmake.buildDirectory": "${workspaceFolder}/build-clangd",
  "cmake.exportCompileCommandsFile": true,
  "cmake.configureOnOpen": true,
  "cmake.configureOnEdit": true,

  "cppIntelligence.clangdPath": "C:/Program Files/LLVM/bin/clangd.exe",
  "cppIntelligence.compilationDatabase": "${workspaceFolder}/build-clangd/compile_commands.json",
  "cppIntelligence.backgroundIndex": true,
  "cppIntelligence.clangTidy": true,
  "cppIntelligence.headerInsertion": "iwyu",
  "cppIntelligence.allScopesCompletion": true,
  "cppIntelligence.completionResultLimit": 500,
  "cppIntelligence.completionRankingModel": "decision_forest",
  "cppIntelligence.frequencyRanking": true,
  "cppIntelligence.suppressTransitiveIncludeInsertion": true,
  "cppIntelligence.cppStandardOverride": "fromBuild",
  "cppIntelligence.includeCompletion": true,
  "cppIntelligence.maxProjectHeaders": 20000,
  "cppIntelligence.fallbackFlags": ["-std=c++23"],
  "cppIntelligence.queryDriver": [],
  "cppIntelligence.autoRestart": true,

  "C_Cpp.intelliSenseEngine": "disabled"
}

If clangd is already on PATH, set cppIntelligence.clangdPath to an empty string. Only add trusted compiler executables to queryDriver; clangd executes these drivers to discover their target and system include paths.

C_Cpp.intelliSenseEngine is only relevant when Microsoft's C/C++ extension is installed. It disables that extension's language provider while allowing you to keep its debugger features.

Generating the compilation database

CMake Tools generates compile_commands.json during configuration. You should not edit this file manually.

With the settings above:

1. Run CMake: Select a Kit and select LLVM/Clang.
2. Run CMake: Configure.
3. Verify ${workspaceFolder}/build-clangd/compile_commands.json.
4. Run C++ Intelligence: Restart Language Servers if the server has not restarted automatically.

If the same build directory was previously configured with a Visual Studio generator, run CMake: Delete Cache and Reconfigure once. Keeping build-clangd separate from another Visual Studio build directory avoids generator-cache conflicts.

The equivalent command-line setup is:

cmake -S . -B build-clangd -G Ninja -DCMAKE_EXPORT_COMPILE_COMMANDS=ON
cmake --build build-clangd

compile_commands.json is supported by CMake's Makefile and Ninja generators. It is not produced by Visual Studio generators.

Multiple targets: Engine and Sandbox

Public library headers must be declared with target_include_directories(... PUBLIC ...). target_link_directories configures library-search paths and does not expose headers.

# Engine/CMakeLists.txt
add_library(Engine STATIC
    src/Engine.cpp
    include/Engine/Engine.h
)

target_include_directories(Engine PUBLIC
    $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include>
    $<INSTALL_INTERFACE:include>
)

# Sandbox/CMakeLists.txt
add_executable(Sandbox main.cpp)
target_link_libraries(Sandbox PRIVATE Engine)

CMake then propagates the Engine include directory into Sandbox's compile command, enabling completion, diagnostics, and navigation for:

#include <Engine/Engine.h>

Headers are usually not listed as independent entries in compile_commands.json; clangd associates them with the most relevant translation unit and target command.

FetchContent and external libraries

The include-completion index reads explicit search roots from the active translation unit's -I, -isystem, /I, and /external:I flags. This covers FetchContent dependencies under build/_deps, vcpkg packages, generated headers, and include roots outside the workspace.

After adding or changing a dependency, run CMake: Configure again. The extension reports C++: stale build config when a CMake input is newer than the compilation database.

Example:

include(FetchContent)

FetchContent_Declare(
    glfw
    GIT_REPOSITORY https://github.com/glfw/glfw.git
    GIT_TAG 3.3.8
)

FetchContent_MakeAvailable(glfw)
target_link_libraries(Engine PUBLIC glfw)

Smarter automatic includes

With headerInsertion set to iwyu, clangd can add a required header when a completion is accepted. This extension removes only insertions that are already reachable through the current project-header chain.

For example:

// mylib.h
#include <iostream>

// main.cpp
#include <mylib.h>

std::cout;

Accepting the std::cout completion does not add a duplicate direct #include <iostream> when cppIntelligence.suppressTransitiveIncludeInsertion is enabled. Headers that are not already reachable are still inserted normally.

Set cppIntelligence.headerInsertion to never to disable all completion-driven include insertion.

C++ standard selection

cppIntelligence.cppStandardOverride defaults to fromBuild. This preserves the exact standard, target, macros, and include paths generated by CMake. Equivalent spellings such as -std=gnu++23 and c++23 are not rewritten.

Available overrides are c++17, c++20, c++23, and c++26. Prefer configuring the standard in CMake:

set(CMAKE_CXX_STANDARD 23)
set(CMAKE_CXX_STANDARD_REQUIRED ON)

Commands

• C++ Intelligence: Restart Language Servers — restart clangd for every workspace folder
• C++ Intelligence: Run Diagnostics — inspect clangd, database entries, include roots, settings, and conflicts
• C++ Intelligence: Open Language Server Log — open the clangd output channel
• C++ Intelligence: Select compile_commands.json — select a database manually

Troubleshooting

The project builds, but headers or methods are reported as missing

Run C++ Intelligence: Run Diagnostics and check the selected database. Reconfigure CMake if the database is missing or stale. The command for the affected .cpp file must contain the same -I, -D, target, and standard flags as the successful build.

A library header is not found from an executable target

Use target_include_directories(Library PUBLIC ...) and link the consuming target with target_link_libraries. Reconfigure CMake and verify that the consumer's entry in compile_commands.json contains the library include directory.

Completion or diagnostics appear twice

Use one C/C++ language provider. Disable Microsoft C/C++ IntelliSense with "C_Cpp.intelliSenseEngine": "disabled", and disable the separate clangd extension. Debugger-only use of Microsoft C/C++ is fine.

CMake reports a generator mismatch

Use a separate directory such as build-clangd, or run CMake: Delete Cache and Reconfigure before changing the generator.

.clangd configuration

Project-specific clangd adjustments can be placed in .clangd at the workspace root:

CompileFlags:
  Add: [-Wall]
  Remove: [-Werror]
Diagnostics:
  UnusedIncludes: Strict

Scope and privacy

The extension supports local files with the language IDs c, cpp, objective-c, objective-cpp, and cuda-cpp. For SSH, WSL, or Dev Containers, install both the extension and clangd in the remote environment.

Language analysis, indexing, and completion-history ranking run locally. The extension does not send source code or telemetry to an external service. CMake itself may access the network when your project uses features such as FetchContent.

License

MIT

References

• clangd project setup
• clangd compile commands
• clangd indexing
• clangd configuration
• CMake Tools settings
• CMake compile commands