C++ Insights: reading your C++ with the eyes of a compiler

The gap C++ Insights fills between your source and the AST

A C++ compiler inserts a great deal that never appears in your file. Defaulted constructors, implicit upcasts, the hidden loop machinery behind a range-based for, the closure type behind a lambda, the deduced type behind auto. Clang will happily dump its AST, and Compiler Explorer will show you assembler, but neither output is written in the language you typed. The README is explicit about this motivation: the author wanted output in the language he writes code in, because an AST dump was not satisfying when teaching students.

C++ Insights is a source-to-source transformation built on Clang. It takes a snippet and returns C++ that spells out the transformations the compiler performs. The README's own example is a Base/Derived pair with a default-constructed object, a copy, an assignment and a reference binding. The transformed output shows the implicitly generated default constructor, copy constructor and copy assignment operator as commented-out declarations inside each class, and rewrites the body of main so that `Derived d2 = d;` becomes `Derived d2 = Derived(d);`, `d2 = d;` becomes `d2.operator=(d);`, and the reference binding becomes `Base & b = static_cast<Base&>(d);`.

The audience follows from that. This is for people who already know C++ and want to see the machinery, and for people teaching it. It is not a linter, not a formatter, and not a code generator you would ship.

How the transformation works, and where it stops

The repository layout makes the architecture visible. The tool is a set of C++ sources built against Clang: `Insights.cpp` and `Insights.h` drive the tool, `ASTHelpers.cpp` and `ASTHelpers.h` sit next to them, and `CodeGenerator.cpp` with `CfrontCodeGenerator.cpp` and `CoroutinesCodeGenerator.cpp` produce the rewritten text. `OutputFormatHelper.cpp` handles how that text is printed. The name CfrontCodeGenerator is a deliberate nod to the original C++ compiler, which emitted C; the generator here emits C++ in a similarly explicit style.

The data flow is therefore one-directional. Clang parses and type-checks your snippet, the tool walks the resulting AST, and the code generators print a new translation unit in which the implicit steps are written out. There is no linker, no execution, and no object code. `LifetimeTracker.cpp` and `StackList.h` suggest the tool also tracks some object lifetimes internally, which matches the goal of showing where temporaries and copies appear.

The README is candid about the boundary. The goal is to produce compilable code, but the author states plainly that this is not possible in all places, and that C++ Insights is based on Clang and its understanding of the AST. That second sentence is the important one: when Clang's model of a construct differs from what you expected, the output inherits that model. Support for newer standards is described in the README as ongoing work rather than complete, and the topics list on the repository reaches as far as C++26, which is a statement of intent rather than a guarantee of coverage.

Building C++ Insights outside the Clang tree

The README gives two build paths. Building outside the Clang source tree is the shorter one, and it requires a Clang installation already in the search path. The commands are a clone, a build directory, a CMake configure with the Ninja generator, and a build.

git clone https://github.com/andreasfertig/cppinsights.git
mkdir build && cd build
cmake -G"Ninja" ../cppinsights
ninja

After `ninja` finishes, the README states that the resulting binary is called `insights` and lives in the `build` folder. Run it against a source file and compare the output with your input.

Building inside the Clang source tree uses the LLVM external projects mechanism instead, which matters if you want the tool to match a specific LLVM checkout rather than whatever Clang your package manager installed. The README's invocation clones both repositories, creates a build directory, and passes the C++ Insights source directory through `LLVM_EXTERNAL_CPPINSIGHTS_SOURCE_DIR`.

git clone https://github.com/llvm/llvm-project.git
git clone https://github.com/andreasfertig/cppinsights.git

mkdir build
cd build
cmake -G Ninja -D=CMAKE_BUILD_TYPE=Release -DLLVM_EXTERNAL_PROJECTS=cppinsights -DLLVM_EXTERNAL_CPPINSIGHTS_SOURCE_DIR=<PATH/TO/cppinsights>  [INSIGHTS CMAKE OPTIONS] ../llvm-project/llvm

ninja

Note that the placeholder `<PATH/TO/cppinsights>` and the bracketed `[INSIGHTS CMAKE OPTIONS]` are reproduced exactly as the README writes them; you supply the real path and any options you want. The CMake option table lists `INSIGHTS_STRIP` (default ON), `INSIGHTS_STATIC` (default OFF), `INSIGHTS_COVERAGE` (default OFF) and `INSIGHTS_USE_LIBCPP`, whose row is cut off in the README text. On Arch Linux the README adds a specific set of flags, `-DINSIGHTS_USE_SYSTEM_INCLUDES=off -DCLANG_LINK_CLANG_DYLIB=on -DLLVM_LINK_LLVM_DYLIB=on`, and links to issue 186 for why `INSIGHTS_USE_SYSTEM_INCLUDES` has to be turned off there. Windows has its own file, Readme_Windows.md, which the README points to rather than reproducing.

The online instance and the Gitpod route

If you only want to see a transformation, the README's first suggestion is the hosted instance at cppinsights.io, which is also the project homepage. The README links example transformations for a lambda, a range-based for-loop and auto, and states that you can transform any other C++ snippet. That is the cheapest way to evaluate whether the tool's output style suits you, and it needs no toolchain at all.

For a full environment without a local Clang, the repository carries a `.gitpod.yml` and the README includes an Open in Gitpod badge pointing at the GitHub repository. That gives you the source and a configured workspace rather than the tool alone.

The trade-off between the two is not subtle. The hosted instance runs whatever version the maintainer has deployed, and the README does not document which Clang version backs it or whether you can select one. A local build lets you pin the Clang version, which is the only way to be sure the transformations you see correspond to the compiler you ship with. If your question is about a construct whose handling changed between standards, the pinned build is the one that answers it.

What C++ Insights is not good at

The most important limitation is stated by the author rather than discovered by a user: producing compilable code is a goal, and it is not achievable in all places. Do not expect to feed the output back into your build and get the same program. Some transformations have no faithful C++ spelling, and the tool has to approximate.

The second limitation is dependency. C++ Insights is built on Clang and inherits its AST, so it shows you Clang's interpretation. If you compile with a different front end, or with a Clang version that models a construct differently, the picture can differ from what your build actually does. The README also notes that support for newer standards was still in progress at the time of writing, so a C++20 or later construct may be handled partially or not at all.

The third limitation is scope. This is an inspection tool. It does not optimise, does not tell you whether your code is correct, and does not replace reading the standard when the question is what the language requires rather than what one implementation does. When you need to know what the emitted machine code looks like, Compiler Explorer is the right instrument, because C++ Insights stops at C++ source.

Compiler Explorer and the standard, as alternatives

The comparison the README draws itself is with Compiler Explorer. Both take a snippet and show you something you did not write. The difference in approach is the output language: Compiler Explorer shows assembler, and C++ Insights shows C++. If your question is why a copy constructor was called, assembler answers it indirectly and C++ answers it in the vocabulary of the language. If your question is whether a loop was vectorised, C++ Insights has nothing to say and Compiler Explorer is the tool.

The AST dump is the other alternative, and it is the one the author tried first. It is complete and authoritative for the Clang version that produced it, but it is a tree of nodes and types, not source text, and the README describes that as the reason for building something else. There is a real cost to that choice: an AST dump cannot be wrong about the AST, while a source-to-source transformation can misrepresent a construct when it has to approximate.

For the underlying language rules, the standard and a reference like cppreference are the authority, and neither C++ Insights nor Compiler Explorer substitutes for them. Use C++ Insights to form the question, then check the answer against the standard.

Licence, releases and the cost of keeping up

The repository is MIT licensed, and the README carries the MIT badge. For most users that is permissive enough to build the tool, read it and use its output in teaching material, but the licence text in the LICENSE file is what governs, and this is not legal advice.

The release cadence in the repository shows v_21.1 in May 2026, v_20.1 in May 2025 and v_19.1 in January 2025, and the last push to the default branch was on 2026-08-26. The repository is not archived. That pattern suggests roughly annual tagged releases with work landing on the branch in between.

The upgrade cost is the part worth thinking about before you depend on it. Because the tool is built against Clang, moving to a newer Clang means rebuilding and rechecking the transformations you care about, and the Arch Linux flags in the README show that linking against system Clang and LLVM libraries is already fiddly. A team that pins a Clang version for its build has to pin C++ Insights to a compatible one too. The version header is generated from `version.h.in`, so the binary reports which build it is.

Editorial conclusion

Adopt C++ Insights if you teach C++, write about the language, or need to explain why a template error or an implicit conversion behaves the way it does; the online instance at cppinsights.io costs nothing to try. Do not put it in a build pipeline, because the README states that producing compilable output is not possible in all places, and do not treat its output as a specification of what your compiler must emit. Before relying on it, build it against the Clang version you actually use and check the transformation you care about against the standard.

Frequently asked questions

Official sources

1. andreasfertig/cppinsights on GitHub
2. License: MIT
3. Project website
4. README
5. Releases