# Add clang-tidy to a CMake C++ Project and Its CI

Yes. An agent adds a .clang-tidy config, an opt-in CMake option that runs clang-tidy during the build, and a CI job that fails on new findings, then opens a PR.

[Run this on Rush](https://cloud.getrush.ai/run/add-clang-tidy/cmake/). Opens the console with this prompt ready to send, in a Project that has your repository.

## 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`

```json
{
  "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"
    }
  ]
}
```

1. **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.
2. **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.
3. **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.

## 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

- [Add CMakePresets.json to a CMake Project](https://getrush.ai/run/add-cmake-presets/cmake/)
- [Add CodeQL Scanning to a CMake C++ Project](https://getrush.ai/run/add-codeql-scanning/cmake/)
- [Add Conan 2 Packaging to a CMake C++ Library](https://getrush.ai/run/add-conan-package/cmake/)

## More jobs like this: Hand off a long task

- [Sort Tailwind CSS Classes with Prettier](https://getrush.ai/run/add-class-sorting/tailwind/)
- [Add Clippy to CI for a Tokio Project](https://getrush.ai/run/add-clippy-to-ci/tokio/)
- [Add CloudWatch Alarms to a Serverless Framework Service](https://getrush.ai/run/add-cloudwatch-alarms/serverless/)

## Keep reading

- [How a Rush run works on your repository, from request to pull request](https://getrush.ai/cloud/)
- [Compare cloud agents, agent sandboxes and AI code review](https://getrush.ai/compare/)
- [Rush pricing: Free, Pro and Max](https://getrush.ai/pricing/)
