C++ Modules Language Servermcppls - C++20/23 named modules that just work: go to definition, completion, hover and references across modules for any compiler, with clangd and a standard library kit built in. Installation Launch VS Code Quick Open ( Ctrl+P), paste the following command, and press enter.Copied to clipboard |
C++ ModulesC++20 and C++23 named modules that just work in VS Code. Open a folder with What you get
Everything ships inside the extension: the language server, clangd 23.1 and the standard library kit. Nothing is downloaded or installed at run time, and nothing is written to your project. StatusWhen a C++ file is open, the language status area shows one item, for example Highlighting
|
| Command | Use |
|---|---|
| C++ Modules: Select Context | Choose the target or configuration a file is analyzed in |
| C++ Modules: Show Module Graph | Modules, the files that provide them, and who imports them |
| C++ Modules: Restart Language Server | Restart the server and clangd |
| C++ Modules: Show Logs | Open the log |
| C++ Modules: Install Command Line Tools | Run xcode-select --install (macOS only) |
| C++ Modules: Collect Diagnostic Report | Open the server's status and this extension's version, settings and other installed C++ extensions as JSON, ready to copy or attach to an issue; your user name, home directory, host name and secrets are replaced |
| C++ Modules: Export Diagnostic Bundle | Write one zip with the report, the environment, the logs of the last sessions, the incidents and the engine database, redacted the same way and checked before it is written; never uploaded |
| C++ Modules: Restart clangd | Restart clangd alone, now, whatever its restart budget says |
| C++ Modules: Reset This Workspace's Cache | Delete this workspace's cache (models, engine database, module cache; the logs stay) and prepare again from a clean state, for when preparation never finishes or clangd keeps crashing. The status offers it for those problems. Needs mcppls 0.0.7 or later |
| C++ Modules: Open the Cache Hub | The menu behind the status bar item's click: the cache against its budget, the sweep, the diagnostics and the feedback actions, in four groups. Needs mcppls 0.0.10 |
| C++ Modules: Sweep the Module Cache (No Restart, No Rebuild) | Remove what no engine holds — dead copies, dead instance directories, trash — without stopping anything or rebuilding a module. The hub's eye button does a dry run first. Needs mcppls 0.0.10 |
| C++ Modules: Copy the Agent Prompt for Cache Troubleshooting | Copy a task book for a local AI agent: verified facts, read-only checks with what healthy looks like, an output contract, and a bug branch where — after you agree — the agent drafts the issue itself and shows it to you first. Logs and bundles never leave the machine by themselves. Needs mcppls 0.0.10 |
| C++ Modules: Copy the Issue Draft Prompt | Copy the companion that turns a finished analysis into an issue draft, for you to read before anything is sent. Needs mcppls 0.0.10 |
| C++ Modules: Reveal the Cache Directory | Open this workspace's module cache in the file manager (the hub's directory drill-down also names the logs and the bundles). Needs mcppls 0.0.10 |
| C++ Modules: Turn Off in This Workspace | Stop the server and keep it off here: writes "mcppls.enable": false to the workspace's settings, and the status bar item says C++ Modules: off in this workspace |
| C++ Modules: Turn On in This Workspace | The other way: removes that setting (or, when it is your user setting that says false, overrides it for this workspace) and starts the server. The status bar item's click does the same |
| C++ Modules: Run the Build Tool in a Terminal | Run the project's build command (mcpp build or the CMake configure step) in your own terminal, where a proxy or credentials you set by hand actually are |
| C++ Modules: Turn Off Other C++ Language Features | Turn off the language features of other active C++ extensions, in this workspace or everywhere (user settings) |
| C++ Modules: Restore Other C++ Language Features | Put back whatever the command above (or the one-time question) last changed, in the same scope |
With mcppls.ai.enabled:
| Command | Use |
|---|---|
| C++ Modules: Review Changes | Review the workspace's changes against HEAD: findings of mcppls's rules — removed or changed exports still in use, partition misuse, unresolved imports, new compiler errors — shown as problems with their evidence as related locations. Runs git and the compiler, so only in a trusted workspace; nothing is sent to a model |
| C++ Modules: Clear Review | Remove the review's problems |
When mcppls cannot recover
Some problems the server cannot fix by itself: clangd that keeps crashing, a payload that does not match its checksum, a clangd that cannot use its cache, modules that never finish preparing. For those the server writes a diagnostic bundle on its own (it stays on your machine, with your user name, home directory, host name and secrets replaced) and the editor shows one notification, never a modal one, with what you can do next:
- Report Issue… shows the bundle in your file manager and opens the bug report form on GitHub already filled in with the versions, the editor and the system. Attach the file and send it, or do not: nothing is uploaded by the extension.
- Restart Server, Reset This Workspace's Cache, Show Logs.
- Turn Off in This Workspace, when this project is one mcppls cannot serve yet.
If the server process itself keeps dying (three times in three minutes) the extension stops restarting it, saves a small crash report (the extension's log, the end of the server's log, versions and system) under its own storage, and shows the same notification for it. With an older server that sends no bundle, Report Issue… writes one first.
Settings
All settings are optional.
| Setting | Default | Use |
|---|---|---|
mcppls.compiler |
automatic | Follow this compiler instead of the discovered one |
mcppls.semanticKit |
auto |
off never uses the built-in standard library kit |
mcppls.engine.name |
clangd |
none runs without clangd: module-level features only. Called mcppls.engine before 0.0.9; a value under the old name still applies, and the extension offers once to move it |
mcppls.engine.workers |
auto |
How many files clangd builds at once; auto, or a whole number from 1 to 99. Takes effect when the server restarts, which a change does by itself |
mcppls.buildDiscovery.mode |
auto |
off detects no build system and runs nothing implicitly. Called mcppls.buildDiscovery before 0.0.9, handled the same way |
mcppls.enable |
true |
false in a workspace's (or folder's) settings starts nothing there: the extension stays installed, activation stays cheap, and the status bar item says the server is off and turns it back on. Changing it takes effect at once |
mcppls.ai.enabled |
false |
Show the review commands |
mcppls.detectConflicts |
true |
Offer once to turn off other C++ extensions' language features in the workspace, and notice again if one becomes active later |
mcppls.semanticTokens.modules |
true |
Module keywords and names from the server's semantic tokens; turn off to use only your own grammar or tree-sitter colors for module syntax |
mcppls.completion.triggerOnSpace |
true |
Show the module list as soon as a space is typed after import or export import; a space anywhere else never reaches the server |
mcppls.trace.server |
off |
Trace the language server protocol in the log |
mcppls.buildTool |
offline |
How mcppls may run the project's build tool (mcpp, CMake) to learn how it is built: offline runs it without the network, offering to run it in a terminal when it needs a download; online lets it reach the network, with up to ten minutes; off never runs it, using only the cache or scanned sources |
mcppls.toolEnvironment |
auto |
Which environment build tools are started in: auto reads the login shell's environment once in the background on Linux and macOS (Windows always matches the editor); editor always uses the editor process's own environment |
Completion while you type
VS Code 1.125 and later keep the completion list closed while an inline completion (GitHub Copilot is
built into VS Code) shows grey text, and otherwise open it only once you stop typing: that is VS Code's
default for editor.quickSuggestions, {"other": "offWhenInlineCompletions"}. For C and C++ files this
extension sets {"other": "on", "comments": "off", "strings": "off"} instead (WA-VSCODE-002): the list
opens as you type and the grey text shows beside it. A value you set under "[cpp]" or "[c]" wins; one
set for every language does not, and the log says so once. Export Diagnostic Bundle records the value
C++ files get and where it comes from.
Other C++ extensions
If the Microsoft C/C++ extension or the clangd extension also serves C++ files, results appear twice. The extension asks once whether to turn their language features off for the workspace; nothing changes without your answer. cpptools keeps its debugger either way — only its IntelliSense engine is turned off.
Turn them off or put them back at any time with C++ Modules: Turn Off Other C++ Language Features and C++ Modules: Restore Other C++ Language Features. If one of them becomes active again later — reinstalled, re-enabled, or its setting turned back on — a notice says so once, with a "Turn Off" action; it is never a warning or error, and nothing changes without you choosing it.
An extension with no setting to turn off (for example ccls) can only be pointed out: the notice's action opens it in the Extensions view, where you can disable it yourself.
This extension and mcpp-community.mcpp-vscode ("mcpp") are separate, and both are worth having installed together: mcpp handles building, toolchains and project operations, while this extension handles C++ module semantics and drives its own pinned clangd. mcpp is not a conflict: it has no language server, and its module grammar uses the same scopes as this extension's own.
macOS Command Line Tools
If the macOS SDK cannot be found, the language status item turns into a warning and the extension offers, once per machine, to run xcode-select --install. Declining changes nothing and is not asked again; the offer is also available any time as C++ Modules: Install Command Line Tools.
Restricted Mode
In an untrusted workspace no compiler, build system or discovery command is run. Module navigation and the built-in standard library kit keep working.
License
Apache-2.0.