C++ Insights is a Clang-based source-to-source transformation tool whose stated purpose is to make visible what normally and intentionally happens behind the scenes: the "magic the compiler does for us to make things work," in the project's own words. Rather than producing assembly or an abstract syntax tree (AST) dump, it rewrites a C++ snippet back into C++ — the language the programmer writes — so that the compiler's internal lowering is readable in familiar syntax.
The opening paragraph introduces C++ Insights as a Clang-based transformation tool whose purpose is to make the compiler's behind-the-scenes lowering visible; the logo identifies the project the article describes.
The motivation comes from a gap in how C++ is usually taught and debugged. Clang can emit an AST dump, and tools like Compiler Explorer can show the assembly a compiler generates from a snippet. But neither output is written in C++, and the project's author says he found that output unfamiliar. When teaching students C++, showing an AST and asserting "it is all there" was not satisfying. C++ Insights was written to close that gap.
The author, Andreas Fertig, began the work in 2017 while studying the new features arriving in C++11, C++14, and C++17 — lambdas, range-based for-loops, and structured bindings — and first presented it as a talk with published slides and video. He then wrote a Clang-based tool that transformed a range-based for-loop into its compiler-internal version, then did the same for structured bindings and lambdas. The project grew beyond those initial targets: it now shows where operators are invoked and where the compiler inserts casts, and it can deduce the type behind `auto` or `decltype`.
The tool's canonical example is a small class hierarchy. Given:
class Base { }; class Derived : public Base { }; int main() { Derived d; Derived d2 = d; d2 = d; Base& b = d; }
C++ Insights produces:
class Base { public: // inline constexpr Base() noexcept = default; // inline constexpr Base(const Base&) noexcept = default; // inline constexpr Base& operator=(const Base&) noexcept = default; }; class Derived : public Base { public: // inline constexpr Derived() noexcept = default; // inline constexpr Derived(const Derived&) noexcept = default; // inline constexpr Derived& operator=(const Derived&) noexcept = default; }; int main() { Derived d; Derived d2 = Derived(d); d2.operator=(d); Base& b = static_cast<Base&>(d); return 0; }
The availability paragraph lists the command-line tool, the cppinsights.io web service, editor integrations, and the Homebrew formula; the repository header points readers to the project's home on GitHub.
The output reveals two things the original source hides. First, the compiler has supplied special member functions — a default constructor, a copy constructor, and a copy assignment operator — for both `Base` and `Derived`, each annotated with `inline constexpr` and `noexcept`. Second, the implicit operations in `main` are rewritten explicitly: the copy `Derived d2 = d` becomes an explicit construction `Derived(d)`, the assignment `d2 = d` becomes an explicit member call `d2.operator=(d)`, and the reference binding `Base& b = d` becomes an explicit upcast `static_cast<Base&>(d)`.
The same mechanism applies to the features the author originally targeted. A range-based for-loop is rewritten into the explicit form the loop desugars to. A lambda is rewritten to show the compiler-generated closure type and its `operator()`. The type deduced behind `auto` or `decltype` is shown in place. The goal throughout is to produce compilable code, although the project notes this is not possible everywhere.
C++ Insights is available as a command-line tool, a web service at cppinsights.io, and integrations for Vim, Neovim, Visual Studio Code, and Homebrew (on macOS). The command-line invocation takes a source file and a standard flag, for example `insights <YOUR_CPP_FILE> -- -std=c++17`. System-include paths are hard-coded from the binary's build compiler, and a helper script, `scripts/getinclude.py`, collects them from the compiler; passing a custom GCC installation that is not on the default path requires a `--gcc-toolchain` argument pointing at the STL location.
Several caveats are stated in the project's own documentation. The author "does not claim to get all the things right." Support for features from newer standards, such as C++20, was in progress at the time of the documentation. The tool is based on Clang and its understanding of the AST, so its output reflects that parser's model of the code. The web service tracks the latest Clang release closely, though its version is often delayed by a few months because of the difficulty of building Clang for Windows.
Because the only substantive source supplied is the project's own repository page, every claim above is attributable to the project's documentation rather than to independent verification. Meaningful unknowns include the exact Clang version the web service currently runs, the completeness of C++20 and later feature support, and how faithfully the rewritten output compiles in edge cases the documentation does not enumerate. For readers who want to test the tool directly, the web service at cppinsights.io requires no local installation.