*Architected by Pavan, written by his friend Claude* I built a CLI tool that audits C++ code across four pillars: memory safety, performance, modern C++ idioms, and architecture. It has internalized the C++ Core Guidelines, Google's Abseil performance wisdom, Scott Meyers' Effective Modern C++, Jason Turner's best practices, and Fedor Pikus' hardware-level optimization techniques. It reads your project, batches the files, sends them to Claude, and returns structured findings with severity levels, code fixes, and source attributions — in your terminal, as markdown, as an interactive HTML report, or as JSON. Here's how we built it, and what it actually knows. ## The Problem C++ performance and safety knowledge is scattered across dozens of authoritative sources: - [C++ Core Guidelines](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines) (Bjarne Stroustrup & Herb Sutter) — hundreds of rules covering memory, concurrency, interfaces - [Google Sanitizers](https://github.com/google/sanitizers/wiki) — AddressSanitizer, ThreadSanitizer, MemorySanitizer, UBSan - [Clang-Tidy](https://clang.llvm.org/extra/clang-tidy/checks/list.html) — bugprone-*, cppcoreguidelines-*, performance-* checks - [Abseil Performance Guide](https://abseil.io/fast/) and [Tips of the Week](https://abseil.io/tips/) — Google's internal C++ wisdom - [Google C++ Style Guide](https://google.github.io/styleguide/cppguide.html) — structural and performance guidance - [Effective Modern C++](https://www.aristeia.com/EMC++.html) (Scott Meyers) — 42 guidelines for modern idioms - [C++ Best Practices](https://github.com/cpp-best-practices/cppbestpractices) (Jason Turner) — practical action items - [The Art of Writing Efficient Programs](https://github.com/PacktPublishing/The-Art-of-Writing-Efficient-Programs) (Fedor Pikus) — hardware-level optimization Unlike .NET where the runtime catches most memory bugs for you, in C++ there is no garbage collector. A missed null check, a dangling reference, a data race — these don't throw polite exceptions. They corrupt memory silently, crash in production, or create security vulnerabilities. No single person holds all of this in their head. But a tool can. ## The Architecture I already had [dotnet-perf-audit](https://github.com/pktikkani/dotnet-perf-audit), a Node.js CLI that audits .NET projects using Claude. The architecture worked well — modular scanner, batched AI analysis, multi-format reporting — so I replicated it for C++. The core pipeline: 1. **Project Scanner** — finds `CMakeLists.txt`, `meson.build`, `Makefile`, `BUILD`, or `*.vcxproj` and extracts C++ standard, dependencies, and linked libraries 2. **File Scanner** — discovers `.cpp`, `.h`, `.hpp`, `.cc`, `.cxx`, `.ipp`, `.tpp` files, skips build dirs and generated code, limits to 50KB/file and 100 files 3. **File Categorizer** — classifies files by content and path: concurrency, allocator, test, main, template, header, implementation 4. **Analyzer** — batches files by token limit (~30K tokens per batch), sends to Claude Sonnet with the four-pillar system prompt, parses JSON findings 5. **Reporters** — terminal (colored + tables), markdown (GitHub PR-ready), HTML (interactive with filtering), JSON ``` cpp-perf-audit ./MyEngine ⚡ cpp-perf-audit v1.0 C++ Performance & Safety Analysis ▸ Project MyEngine (C++17) ▸ Build cmake ▸ Dependencies Threads, Boost, fmt ▸ Files 3 concurrency, 12 implementation, 8 header, 2 test Safety Score: 62/100 ████████████████░░░░░░░░ ``` ## The Four Pillars ### Pillar 1: Memory Safety & Undefined Behavior — HIGHEST PRIORITY Every review starts here. This is where C++ differs massively from managed languages. **Raw owning pointers** — the agent treats these like fire: ```cpp // CRITICAL — raw owning pointer without RAII int* data = new int[1024]; process(data); delete[] data; // what if process() throws? // Fix: RAII wrapper eliminates the leak auto data = std::make_unique(1024); process(data.get()); // automatically freed, even on exception ``` **Use-after-move** — the compiler won't stop you: ```cpp // CRITICAL — undefined behavior std::vector v = {1, 2, 3}; auto v2 = std::move(v); v.push_back(4); // v is in a valid-but-unspecified state // Fix: don't use moved-from objects auto v2 = std::move(v); v.clear(); // or reassign: v = {4, 5, 6}; ``` **Dangling string_view** — looks safe, isn't: ```cpp // CRITICAL — string_view outlives the temporary std::string_view get_name() { std::string name = "hello"; return name; // dangling — name destroyed at end of scope } // Fix: return std::string, or ensure lifetime std::string get_name() { return "hello"; } ``` **Data races** — the silent corruptor: ```cpp // CRITICAL — writing m_running without synchronization void Server::stop() { m_running = false; // data race with worker threads reading m_running for (auto& t : m_workers) t.join(); } // Fix: use std::atomic std::atomic m_running{true}; ``` The agent references specific C++ Core Guidelines for every finding: R.1 (manage resources with RAII), R.11 (avoid explicit new/delete), CP.2 (avoid data races), F.43 (never return pointer to local), C.35 (base destructor must be public+virtual or protected+nonvirtual). It also recommends specific sanitizers — ASan for use-after-free and buffer overflows, TSan for data races, MSan for uninitialized reads, UBSan for signed overflow and null dereference. ### Pillar 2: Performance Issues **Copy in range-for** — a mistake I see in every codebase: ```cpp // WARNING — copies every string on each iteration for (auto item : items) { std::cout << item << std::endl; // also: endl forces buffer flush } // Fix: const reference + '\n' for (const auto& item : items) { std::cout << item << '\n'; } ``` **Missing reserve** — vector reallocates exponentially: ```cpp // WARNING — up to log2(n) reallocations and copies std::vector results; for (int i = 0; i < 10000; i++) { results.push_back(compute(i)); } // Fix: reserve when size is known std::vector results; results.reserve(10000); ``` **Cache-unfriendly containers** — `std::map` vs `std::unordered_map`: ```cpp // WARNING — std::map is a red-black tree, O(log n) with pointer chasing std::map configs; // Fix: unordered_map is O(1) amortized with contiguous buckets std::unordered_map configs; // Or for static data: sorted std::vector + binary search ``` **shared_ptr where unique_ptr suffices** — atomic reference counting has real cost: ```cpp // WARNING — shared_ptr has atomic ref count overhead on every copy auto config = std::make_shared(load()); process(config); // unique ownership would suffice // Fix: unique_ptr when ownership isn't shared auto config = std::make_unique(load()); process(*config); ``` These rules come from the [Abseil Performance Guide](https://abseil.io/fast/) and [Tips of the Week](https://abseil.io/tips/) — Google's production C++ wisdom distilled from billion-line codebases. ### Pillar 3: Modern C++ Improvements From [Scott Meyers' Effective Modern C++](https://www.aristeia.com/EMC++.html) — 20 specific items encoded: ```cpp // SUGGESTION — missing noexcept on move (Item 14) // This silently disables move semantics in std::vector reallocation MyClass(MyClass&& other) { data_ = std::move(other.data_); } // Fix: declare noexcept — vector will now move instead of copy on resize MyClass(MyClass&& other) noexcept { data_ = std::move(other.data_); } ``` ```cpp // SUGGESTION — use make_unique over raw new (Item 21) auto widget = std::unique_ptr(new Widget(args)); // Fix: exception-safe and avoids redundant type name auto widget = std::make_unique(args); ``` From [Jason Turner's Best Practices](https://github.com/cpp-best-practices/cppbestpractices): ```cpp // SUGGESTION — use [[nodiscard]] for functions whose return values matter bool validate(const Config& config) { /* ... */ } validate(config); // silently ignores result // Fix: [[nodiscard]] bool validate(const Config& config) { /* ... */ } validate(config); // compiler warning if result is ignored ``` From [Fedor Pikus](https://github.com/PacktPublishing/The-Art-of-Writing-Efficient-Programs) — hardware-level patterns for hot paths: - **Cache line awareness**: 64 bytes typically — avoid false sharing in concurrent code by padding or aligning atomic variables - **Branch prediction**: organize conditionals with the common case first - **CRTP over virtual dispatch** in performance-critical loops — avoids vtable indirection - **SIMD-friendly data layouts**: struct-of-arrays instead of array-of-structs for SIMD vectorization ### Pillar 4: Architecture The agent checks build system hygiene — and treats missing sanitizer integration as a **Critical** finding: ```cmake # CRITICAL — no sanitizer integration # Your build system should support: target_compile_options(${PROJECT_NAME} PRIVATE $<$:-fsanitize=address,undefined -fno-omit-frame-pointer> ) target_link_options(${PROJECT_NAME} PRIVATE $<$:-fsanitize=address,undefined> ) ``` It also checks: - **Header hygiene** — include-what-you-use, forward declarations, `#pragma once` - **Namespace discipline** — flags `using namespace std;` in headers - **Class design** — Rule of Zero/Five, proper virtual destructor on base classes - **Warning levels** — recommends `-Wall -Wextra -Wpedantic -Werror` ## The Scoring Same algorithm as the .NET tool — simple and transparent: | Finding Type | Penalty | |-------------|---------| | Critical | -15 points | | Warning | -5 points | | Suggestion | -1 point | | Good Pattern | 0 (recognized and highlighted) | Starting from 100, clamped to 0. A project with 3 critical findings and 2 warnings already scores 45/100. ## Shell Integration with fzf Both tools have fzf-powered project selection. Type `cppaudit` with no arguments and it uses `fd` to find every C++ project on your machine, pipes through `fzf` for interactive selection: ```bash # Interactive picker — finds CMakeLists.txt, Makefile, meson.build across your dirs cppaudit # Direct path cppaudit ./MyEngine # HTML report cppaudit ./MyEngine -f html # CI mode — exits 1 if critical findings cppaudit ./MyEngine --ci ``` Same for .NET: ```bash dotnetaudit # fzf picks from .csproj/.sln files dotnetaudit ./MyApi -f html ``` Quick aliases: `cppaudit-html`, `cppaudit-ci`, `cppaudit-md`, `dotnetaudit-html`, `dotnetaudit-ci`, `dotnetaudit-md`. ## Red/Green TDD The project has 85 tests across 6 test files, built with red/green TDD: - **File categorizer** (22 tests) — content-based and path-based categorization for concurrency, allocator, test, main, template, header, implementation - **Project scanner** (6 tests) — CMake parsing, C++ standard extraction, dependency extraction with version parsing - **File scanner** (9 tests) — discovery, content loading, line counting, category assignment, priority sorting - **Analyzer prompts** (17 tests) — validates all four pillars are present, all sources referenced (Core Guidelines, sanitizers, Scott Meyers, Jason Turner, Abseil, Fedor Pikus, Clang-Tidy) - **Reporters** (19 tests) — markdown and HTML generation with correct project info, findings, scores, code blocks - **Theme** (12 tests) — severity colors, icons, progress bar rendering The RED phase caught a real bug — the CMake `find_package` regex was capturing trailing parentheses in version strings (`1.80)` instead of `1.80`). Fixed in the GREEN phase. ## The Sources Everything in the tool is grounded in these authoritative references: | Pillar | Primary Source | Link | |--------|---------------|------| | Bugs/Critical | C++ Core Guidelines | [isocpp.github.io](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines) | | Bugs/Critical | Google Sanitizers | [github.com/google/sanitizers](https://github.com/google/sanitizers/wiki) | | Bugs/Critical | Clang-Tidy | [clang.llvm.org](https://clang.llvm.org/extra/clang-tidy/) | | Performance | Abseil Performance + Tips | [abseil.io/fast](https://abseil.io/fast/) and [abseil.io/tips](https://abseil.io/tips/) | | Performance | Google C++ Style Guide | [google.github.io](https://google.github.io/styleguide/cppguide.html) | | Improvements | Effective Modern C++ | [aristeia.com](https://www.aristeia.com/EMC++.html) | | Improvements | C++ Best Practices | [github.com/cpp-best-practices](https://github.com/cpp-best-practices/cppbestpractices) | | Improvements | Art of Writing Efficient Programs | [github.com/PacktPublishing](https://github.com/PacktPublishing/The-Art-of-Writing-Efficient-Programs) | | Master Index | AwesomePerfCpp | [github.com/fenbf](https://github.com/fenbf/AwesomePerfCpp) | ## What I Learned **C++ safety is a fundamentally different problem from .NET performance.** In .NET, the runtime protects you — the agent mostly finds performance inefficiencies. In C++, the agent's Pillar 1 findings are often *security vulnerabilities* and *undefined behavior* that corrupt memory silently. The severity escalation rules had to be much more aggressive. **Build system awareness matters.** A .NET audit only needs to find `.csproj` files. C++ has CMake, Meson, Bazel, Make, vcxproj — each with different syntax for extracting the C++ standard, dependencies, and compiler flags. The project scanner had to handle all five. **File categorization drives analysis quality.** Analyzing a concurrency-heavy file with threading primitives needs different scrutiny than a header with template metaprogramming. By categorizing and prioritizing files (concurrency first, tests last), the most critical code gets analyzed first when token budgets are tight. **The same architecture scales across languages.** Scanner → Categorizer → Batched AI Analysis → Multi-format Reporter. The .NET and C++ tools share the same pipeline structure — only the scanner patterns, file categories, and system prompt change. This could extend to Rust, Go, or any language with its own performance ecosystem. The tool is on GitHub at [pktikkani/cpp-perf-audit](https://github.com/pktikkani/cpp-perf-audit). The .NET sibling is at [pktikkani/dotnet-perf-audit](https://github.com/pktikkani/dotnet-perf-audit).