What the agent does
The agent reads the build and the checks that exist. In a project like jarro2783/cxxopts, the library is one header, include/cxxopts.hpp, exported as an INTERFACE target; CMakeLists.txt declares cmake_minimum_required(VERSION 3.5...3.19) and options CXXOPTS_BUILD_EXAMPLES, CXXOPTS_BUILD_TESTS, CXXOPTS_ENABLE_INSTALL and CXXOPTS_ENABLE_WARNINGS, all on when the project is built standalone. cmake/cxxopts.cmake holds cxxopts_enable_warnings, which adds -Wall -Werror -Wextra -Wshadow -Weffc++ and more on GCC and Clang, and cxxopts_set_cxx_standard, which picks C++11 unless CXXOPTS_CXX_STANDARD says otherwise. The translation units are src/example.cpp, built with cxx_std_17, and the Catch tests under test/, where test/options.cpp is the bulk and test/catch.hpp is a vendored third-party header. .github/workflows/cmake.yml builds on two Ubuntu releases with g++-9, g++-10 and clang++, on macOS with CMAKE_EXPORT_COMPILE_COMMANDS=ON, and on Windows with ClangCl; there is a .clang-format but no .clang-tidy.
It writes a .clang-tidy at the repository root with a Checks list built from bugprone-*, performance-*, modernize-* and readability-* with the checks that would rewrite the C++11 header into later standards turned off, WarningsAsErrors: '*' so a finding is a failure, and a HeaderFilterRegex that matches include/cxxopts.hpp and nothing under test/, so the library header is analysed through every translation unit that includes it while the vendored catch.hpp is not. The regex is the key decision in a header-only project: without it clang-tidy reports only on .cpp files, and with a looser one it drowns in a third-party header.
In CMakeLists.txt a new option CXXOPTS_ENABLE_CLANG_TIDY, default OFF, uses find_program to locate clang-tidy and sets CMAKE_CXX_CLANG_TIDY so every compile of example, options_test and the other test executables is checked as it is built. The agent notes that CMAKE_CXX_CLANG_TIDY exists from CMake 3.6, above the project's 3.5 floor, so the option is a no-op on an older CMake and the floor is not raised. A new job in cmake.yml, on ubuntu-24.04, installs clang-tidy, configures with -DCXXOPTS_ENABLE_CLANG_TIDY=ON -DCMAKE_EXPORT_COMPILE_COMMANDS=ON and builds, so a finding fails the job the same way a compiler error would. The existing matrix jobs are untouched.
The first run decides the baseline. The agent builds with the option on in the sandbox, with the same -Werror warnings the project already enforces, and reads every diagnostic. A finding with a mechanical fix in src/example.cpp or the tests gets the fix in the same pull request; a check that fires across include/cxxopts.hpp in a way that is a style choice is turned off in .clang-tidy with a one-line comment naming it, so the job is green on its first run and every disabled check is visible for the maintainer to turn back on. ctest runs afterwards to show the tests still pass.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "Add clang-tidy to this CMake C++ project. Read CMakeLists.txt, cmake/cxxopts.cmake, src/CMakeLists.txt, test/CMakeLists.txt, .clang-format and the GitHub Actions workflows first. Write a .clang-tidy with bugprone, performance, modernize and readability checks, with checks that would move the header past C++11 disabled, WarningsAsErrors set to all, and a HeaderFilterRegex that covers include/cxxopts.hpp and excludes test/catch.hpp. Add a CXXOPTS_ENABLE_CLANG_TIDY option, default off, that finds clang-tidy and sets CMAKE_CXX_CLANG_TIDY, and note the CMake version it needs. Add a job to the CMake workflow on ubuntu-24.04 that installs clang-tidy and builds with the option on and compile commands exported. Build with the option on in the sandbox, fix findings with mechanical fixes in the example and tests, disable with a comment any check that is a style choice in the header, run ctest, and open a pull request that lists every finding and what was done with it. Do not change the warning flags or the C++ standard.",
"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
What comes back is a pull request on its own branch with .clang-tidy, the option and its find_program in CMakeLists.txt, the new job in .github/workflows/cmake.yml, and whatever mechanical fixes the first run justified in src/example.cpp or under test/. The warning flags, the C++ standard and the vendored catch.hpp are unchanged.
The description lists every diagnostic the first build produced, grouped by check, with what was done: fixed, or disabled with the comment that now sits in .clang-tidy. It ends with the build output showing clang-tidy ran over each translation unit and the ctest summary. The commands and output are in the transcript at GET /o/{org}/sessions/{id}/messages.
Before merging, a maintainer reads the disabled checks and decides which to re-enable in a follow-up, confirms the Ubuntu job's clang-tidy version is one they are happy to track, and watches the job run once on the pull request itself. A follow-up message to the same session can re-enable one check and fix what it finds.
Run it on every terminal hand-off
A maintainer who has wanted static analysis for a while starts this from the terminal with this body and returns to reviewing issues. The run reads the real CMakeLists.txt and workflows, so the option name, the job and the header filter fit this project rather than a template.
Send a request_id, a UUID, with the body so a retried start returns the run it already began. The pull request is on the run's GET /o/{org}/sessions/{id} answer once it is open.
The use case this job follows, with its automation and trigger: Hand off a long task.
Why run it on Rush?
Adding a static analyser to an existing codebase is mostly triage: the first run produces findings, and someone has to read each one, fix it or justify turning it off, and do that before CI goes red for everyone. The agent does the triage in a sandbox with the project's own compiler flags and -Werror, and makes every decision visible in .clang-tidy and the pull request.
The pull request carries the first run's full list and the green build and test output. Several projects can be done at once, each in its own sandbox, each with one pull request.
Frequently asked questions
Will the existing CI jobs slow down?
No. The option defaults to off, so the Ubuntu, macOS and Windows matrix jobs build exactly as before. Only the new job turns it on, and it runs in parallel with them.
How can clang-tidy check a header-only library?
clang-tidy analyses translation units, and reports on headers only when HeaderFilterRegex matches them. The regex in the pull request names include/cxxopts.hpp, so the header is checked every time src/example.cpp or a test includes it, while the vendored test/catch.hpp stays out.
Why disable some checks instead of fixing everything?
Some modernize checks would rewrite a C++11 library in C++14 or C++17 idioms, which is a design decision for the maintainer, not a lint fix. Those are turned off with a comment in .clang-tidy so they are a one-line change to bring back, and the pull request lists each one.
Does this change the minimum CMake version?
No. CMAKE_CXX_CLANG_TIDY appeared in CMake 3.6 and the project's floor is 3.5, so the option is simply ignored on an older CMake. The pull request notes it; every runner in the workflow has a far newer CMake.
More CMake jobs
More jobs like this: Hand off a long task
- Sort Tailwind CSS Classes with Prettier (Tailwind CSS)
- Add Clippy to CI for a Tokio Project (Tokio)
- Add CloudWatch Alarms to a Serverless Framework Service (Serverless Framework)