What the agent does
The agent reads how the project is built in CI before adding an analyser to it. In a library laid out like jarro2783/cxxopts, CMakeLists.txt requires CMake 3.5 and declares cxxopts as an INTERFACE library whose single header, include/cxxopts.hpp, is 3,192 lines; the options CXXOPTS_BUILD_EXAMPLES, CXXOPTS_BUILD_TESTS and CXXOPTS_ENABLE_WARNINGS default to on for a standalone build, cmake/cxxopts.cmake sets C++11 with extensions off and a -Wall -Werror -Wextra -Wshadow -Weffc++ -Wconversion set for GCC and Clang, and test/CMakeLists.txt builds options_test and options_test_noregex from main.cpp and options.cpp against the vendored catch.hpp, plus no-exception smoke tests, a fuzzer under Clang, and find-package, add-subdirectory and pkg-config tests. .github/workflows/cmake.yml builds on Ubuntu 22.04 and 24.04 with g++-9, g++-10 and clang++, on macOS with -DCMAKE_EXPORT_COMPILE_COMMANDS=ON, and on Windows with ClangCL; build.yml is a plain cmake .. and make, meson.yml covers the Meson build, and cifuzz.yml runs OSS-Fuzz. The warnings-as-errors flags are the only static checking.
The job the agent adds to cmake.yml, cppcheck, runs on ubuntu-24.04, whose apt package is Cppcheck 2.13, installs it, configures the project with -DCMAKE_EXPORT_COMPILE_COMMANDS=ON as the macOS job already does, and runs cppcheck --project=build/compile_commands.json. The compilation database is the right input for a header-only library: Cppcheck checks headers through the translation units that include them, so include/cxxopts.hpp is analysed as test/options.cpp, src/example.cpp and the other test sources see it, with the include paths and defines CMake recorded, including CXXOPTS_NO_REGEX for the second test binary. The flags are --enable=warning,style,performance,portability, leaving out unusedFunction, which is wrong for a library and for Catch's registration macros, and missingInclude; --std=c++11 to match cxxopts_set_cxx_standard; --inline-suppr so a // cppcheck-suppress comment in the header works; --error-exitcode=1 so a finding fails the job; and -j set to the runner's cores.
Suppressions keep the job about the library's code. --suppress=*:*/catch.hpp silences everything in the vendored test framework, which is not this project's to fix, with the [id]:[file] wildcard form the manual gives; -i build keeps the configure tree out; and a .cppcheck-suppressions file read with --suppressions-list holds any per-line entry with a comment saying why, so the workflow line stays short. The agent runs the job's command in its sandbox on the real tree first, reads every finding in cxxopts.hpp, options.cpp and example.cpp, fixes what is a real issue, adds an inline suppression with the check id for a pattern the library uses on purpose, such as a constructor the style check wants explicit where implicit conversion is the API, and records each decision in the pull request. --check-level=exhaustive is left as a documented option, since the normal level is the default and the exhaustive one costs minutes on a 3,000-line header.
A second configuration covers the CXXOPTS_NO_EXCEPTIONS builds, because the no-exception smoke tests compile the header with a different define and Cppcheck checks one preprocessor configuration per file by default; the job runs a second time with -DCXXOPTS_NO_EXCEPTIONS added through --project on a build configured that way, rather than --force, which would walk every #ifdef combination. The workflow uploads the --xml output as an artifact on failure so a finding can be read without re-running, and README.md gets the two commands under a Static analysis heading so a contributor can run the same check locally before pushing.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "Add Cppcheck to CI for this CMake project. Read CMakeLists.txt, cmake/cxxopts.cmake, include/CMakeLists.txt, src/CMakeLists.txt, test/CMakeLists.txt and every workflow under .github/workflows first. Add a cppcheck job to the CMake workflow on ubuntu-24.04 that installs Cppcheck from apt, configures with CMAKE_EXPORT_COMPILE_COMMANDS on, and runs cppcheck with --project on the compilation database, --enable=warning,style,performance,portability, --std matching the project's standard, --inline-suppr, --error-exitcode=1, -j, a suppression for everything in the vendored catch.hpp, -i for the build directory, and a suppressions list file for per-line entries with reasons. Run it in the sandbox on the real tree, fix real findings, add inline suppressions with the check id and a reason for patterns the library uses on purpose, and list each decision. Add a second run on a build configured with the no-exceptions define. Upload the XML output as an artifact on failure and document the local command in the README. Run the existing tests after your fixes and open a pull request quoting the Cppcheck output before and after.",
"resources": [
{
"url": "https://github.com/your-org/your-app"
}
]
}- Get an API key. In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
- Send the request. POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
- Read what came back. Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.
What comes back
The pull request adds .cppcheck-suppressions and changes .github/workflows/cmake.yml, README.md, and whichever of include/cxxopts.hpp, test/options.cpp and src/example.cpp had a finding worth fixing or an inline suppression. Its description quotes the Cppcheck output from the first run on the untouched tree, a table with one row per finding naming the check id, the file and line and what was done, the clean run after the changes for both configurations, and the ctest result showing the test binaries still pass under the project's -Werror flags.
A reviewer reads the fixes as ordinary code changes, checks each suppression's reason, and decides whether unusedFunction or --check-level=exhaustive is worth the extra time on their runners. They also decide whether the job should block merging, which is a branch-protection setting the pull request names but does not change.
The compiler matrix, the macOS and Windows jobs, the Meson workflow and the fuzzing job are untouched, and Cppcheck adds no dependency to the library itself.
Run it on every C++ repository without static analysis
An organisation with several CMake projects can send this body once per repository from a short script on its own server: list what the GitHub App reaches with GET /o/{org}/github, keep the repositories whose default branch has a CMakeLists.txt and no cppcheck in .github/workflows, and give each request a request_id that is a UUID v5 of the repository's full name so a rerun returns the runs it already started. Each run opens one pull request fitted to that project's standard, defines and vendored headers, and the key's webhook_url receives run.completed for each.
Once the job is in, an automation on the Project with a github trigger on workflow_run.failure can run read-only with a prompt that reads the failed job's Cppcheck XML artifact and comments on the pull request with each finding's file, line and check id. The trigger adds the event after the prompt; it fills in no placeholder.
The use case this job follows, with its automation and trigger: Hand off a long task.
Why run it on Rush?
Cppcheck on a header-only library is mostly about what to feed it and what to ignore: the compilation database so the header is seen through real translation units with the right defines, a suppression for the vendored test framework, a second configuration for the define that changes the header's shape, and a first run whose findings someone has to read. The agent reads the CMake files and the workflow matrix, runs the analyser on the real tree in its sandbox before writing the job, and handles each finding with a fix or a reasoned suppression, with the output kept in the run's record.
The job that lands is one a contributor can reproduce with two commands from the README, which is what makes a static-analysis gate something people fix rather than disable.
Frequently asked questions
Why use compile_commands.json for a header-only library?
Cppcheck analyses a header through the source files that include it, so pointing it at include/ alone finds nothing. The compilation database lists test/options.cpp, src/example.cpp and the other test sources with their include paths and defines, so cxxopts.hpp is checked in each context it is compiled in.
Will catch.hpp findings fail the job?
No. --suppress=*:*/catch.hpp silences every check id in that file, using the wildcard form Cppcheck's manual gives for suppressions. -i would not do it, because an ignored path only skips translation units, and a header included from a checked source is still analysed.
What about the no-exceptions build?
Cppcheck checks one preprocessor configuration per file by default, so the CXXOPTS_NO_EXCEPTIONS branches of the header would go unchecked. The job configures the project a second time with that define and runs --project on its database, which covers those branches without --force walking every #ifdef combination.
Why not --enable=all?
all includes unusedFunction, which reports every public function of a library nobody calls inside the repository, and missingInclude, which reports system headers. The job enables warning, style, performance and portability, and the README shows how to add the rest locally.
Does the job block merging?
It fails on a finding because of --error-exitcode=1, and whether a failed check blocks a merge is a branch-protection rule on the repository. The pull request names the job so it can be required, and leaves that setting to the maintainers.
More CMake jobs
More jobs like this: Hand off a long task
- Add Crash Reporting to an Electron App (Electron)
- Add Crash Reporting to an Expo App (Expo)
- Add Crash Reporting to a Flutter App (Flutter)