C++ Unused Includes Remover

A VS Code extension that automatically removes unused #include directives from C/C++ files using diagnostics from clangd.

Features

Prerequisites

• clangd VS Code extension (llvm-vs-code-extensions.vscode-clangd)
• clangd binary installed on the system (clangd 17+ recommended for -std=c++23 support)

Installing the clangd binary

The VS Code clangd extension requires the clangd binary to be installed separately.

Debian/Ubuntu (via LLVM apt repository):

# Add LLVM GPG key
wget -qO- https://apt.llvm.org/llvm-snapshot.gpg.key \
  | sudo tee /etc/apt/trusted.gpg.d/apt.llvm.org.asc > /dev/null

# Add repository (adjust codename: bookworm, jammy, etc.)
echo "deb http://apt.llvm.org/bookworm/ llvm-toolchain-bookworm-19 main" \
  | sudo tee /etc/apt/sources.list.d/llvm.list

sudo apt-get update && sudo apt-get install -y clangd-19
sudo update-alternatives --install /usr/bin/clangd clangd /usr/bin/clangd-19 100

Note: The version provided by apt-get install clangd (without a version suffix) is typically outdated. Use the LLVM apt repository to get a recent version.

Enabling unused-includes diagnostics

Create a .clangd file at your project root:

Diagnostics:
  UnusedIncludes: Strict

To also set the C++ standard:

CompileFlags:
  Add: [-std=c++23]
Diagnostics:
  UnusedIncludes: Strict

Note: compile_commands.json is not strictly required, but clangd's accuracy improves significantly with it. For CMake projects: cmake -DCMAKE_EXPORT_COMPILE_COMMANDS=ON -B build For Make-based projects: bear -- make

Using clangd alongside Microsoft C/C++ extension

If the Microsoft C/C++ extension is also installed, disable its IntelliSense engine to avoid conflicts:

// .vscode/settings.json
{
  "C_Cpp.intelliSenseEngine": "disabled"
}

With this setting, clangd handles all language features and the Microsoft C/C++ extension provides only its debugger.

Installation

From VSIX

npm install
npx vsce package

Then install the generated .vsix file via Extensions: Install from VSIX... in the Command Palette.

Development (F5)

npm install
npm run compile

Press F5 in VS Code to launch the Extension Development Host.

Configuration

{
  // Enable auto-removal on save (default: true)
  "cppUnusedIncludes.enableOnSave": true,

  // Diagnostic source name to match against (default: "clangd")
  "cppUnusedIncludes.diagnosticSource": "clangd",

  // Milliseconds to wait after save before reading diagnostics (default: 100)
  // Increase if includes are not removed (language server still analyzing).
  "cppUnusedIncludes.waitForDiagnosticsMs": 100,

  // Glob pattern for files targeted by the workspace-wide command
  "cppUnusedIncludes.workspaceFileGlob": "**/*.{cpp,cc,cxx,c,h,hpp,hxx}"
}

Commands

Run commands from the Command Palette (Ctrl+Shift+P / Cmd+Shift+P).

Troubleshooting

Includes are not being removed

1. Open the Output panel (View > Output) and select C++ Unused Includes Remover from the dropdown.
2. Save a C++ file and check the log.

no diagnostics — clangd is not providing diagnostics. Check that:

• The clangd VS Code extension is installed and active.
• The clangd binary is installed (clangd --version in the terminal).
• A .clangd file with UnusedIncludes: Strict exists at the project root.
• The file has been open long enough for clangd to finish analyzing.

0 unused include(s) to remove — Diagnostics are present but none match. Run C++: Dump Diagnostics to Output (Debug) and verify that source="clangd" entries appear.

Timing issues

If diagnostics are not ready when the extension reads them, no includes will be removed. Increase the wait time:

{
  "cppUnusedIncludes.waitForDiagnosticsMs": 500
}

How It Works

File saved
    │
    ▼
Wait waitForDiagnosticsMs (default: 100ms)
    │
    ▼
vscode.languages.getDiagnostics() — fetch diagnostics
    │
    ▼
Filter: source === "clangd"
        AND (code === "unused-includes" OR message contains "unused"+"include")
    │
    ▼
Sort by line number descending (prevents line-number drift)
    │
    ▼
Delete each #include line via WorkspaceEdit
    │
    ▼
Save document

Development

Using Dev Container (recommended)

This repository includes a Dev Container configuration. You can develop the extension in a fully pre-configured environment without installing anything locally.

Requirements: Docker and either VS Code with the Dev Containers extension or GitHub Codespaces.

1. Open the repository in VS Code.
2. When prompted, click Reopen in Container (or run Dev Containers: Reopen in Container from the Command Palette).
3. The container will automatically run npm install via postCreateCommand.
4. Once the container is ready, press F5 to launch the Extension Development Host.

Local Setup

# Install dependencies
npm install

# Compile TypeScript
npm run compile

# Watch mode (recompile on change)
npm run watch

# Lint / format
npm run check

License

MIT