# Add a clang-format Check to CI for a CMake Project

Yes. An agent measures how far your C++ sources drift from your own .clang-format, adds a CI job that checks only the lines a pull request changes, and opens a PR.

[Run this on Rush](https://cloud.getrush.ai/run/add-clang-format-check/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 style file and the CI before it decides what to enforce. In a header-only library like jarro2783/cxxopts, `.clang-format` has been in the repository since the changelog entry that added it: LLVM-based, `PointerAlignment: Left`, `BreakBeforeBraces: Custom` with braces on their own line after functions, classes, namespaces and control statements, `AlwaysBreakAfterReturnType: TopLevel` and two-space continuation indents. Four workflows under `.github/workflows/` build and test with CMake across Ubuntu, macOS and Windows (`cmake.yml`), with Meson (`meson.yml`), with a plain `make` (`build.yml`) and under OSS-Fuzz (`cifuzz.yml`); none of them runs clang-format. The code is `include/cxxopts.hpp` at a little over three thousand lines, `src/example.cpp`, and `test/options.cpp` plus a few small test sources, with Catch's `catch.hpp` vendored in `test/`.

Measuring comes before enforcing, because a check that fails on day one gets disabled. The agent installs a current clang-format in the sandbox and runs it in `--dry-run` mode over the header, the example and the tests with the repository's own file. On this repository the header reports findings on hundreds of lines and a full reformat would rewrite more than half of it; `test/options.cpp` is in the same state, `test/link_b.cpp` and `test/fuzz.cpp` are already clean. Reformatting everything would turn a two-line style check into a pull request that touches every function in the public header and buries real changes in `git blame`, so the agent does not do that.

Instead it adds a job that checks only what a pull request touches. A new `format.yml` workflow runs on `pull_request`, checks out with enough history to see the base, installs `clang-format` from the Ubuntu runner's packages at a pinned major version, and runs `git clang-format --diff <base-sha> --extensions cpp,hpp -- include src test` with `catch.hpp` excluded, failing when the output is not empty and printing the diff so the author sees exactly what to change. A second, non-blocking step runs the full `--dry-run` count over the tree and writes it to the job summary, so the number is visible on every pull request and the team can watch it fall. The agent also adds a `.clang-format-ignore` for `test/catch.hpp` so a local `clang-format -i` never touches the vendored file.

The proof is the job running on the pull request itself. The agent pushes the branch, waits for the new workflow, and shows the check passing on its own change, which touches only YAML, and a second run on a throwaway commit that mis-indents one function in `src/example.cpp`, which fails with the expected diff, before that commit is dropped. The `cmake.yml`, `meson.yml`, `build.yml` and `cifuzz.yml` jobs are untouched and still pass, because no C++ file changes.

## Start it with one API call

`POST https://api.phoenix.so/o/{org}/sessions`

```json
{
  "agent": "claude",
  "input": "Add a clang-format check to CI for this CMake project. Read .clang-format, CMakeLists.txt, every workflow under .github/workflows, CHANGELOG.md and the layout of include, src and test first. Install clang-format in the sandbox and measure, with the repository's own .clang-format in dry-run mode, how many findings the header, the example and each test source have today; put those counts in the pull request. Do not reformat existing code. Add a format.yml workflow on pull_request that runs git clang-format against the base commit over include, src and test with the vendored catch.hpp excluded, fails and prints the diff when a changed line is misformatted, and adds the full-tree dry-run count to the job summary without failing on it. Add a .clang-format-ignore for the vendored header. Push the branch, show the new job passing on it and failing on a deliberately misformatted throwaway commit that you then drop, and open a pull request.",
  "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 two new files, `.github/workflows/format.yml` and `.clang-format-ignore`, and no change to any C++ source, to `CMakeLists.txt` or to the four existing workflows. The job appears as a required-check candidate on the pull request itself, green, beside the CMake, Meson, build and fuzz jobs.

The description carries the dry-run counts per file as the agent measured them, so a reviewer knows how much drift exists before deciding how to treat it, plus a link to the failing run on the throwaway commit with its printed diff. The transcript at `GET /o/{org}/sessions/{id}/messages` keeps every command, the two measurements included.

Before merging, a reviewer decides the clang-format major version to pin, whether the check should also run on `push` to `master`, and whether to schedule a one-time reformat of the header in a release where nothing else changes. A follow-up message to the same session can produce that reformat as a separate pull request, or add a `pre-commit` hook that runs the same `git clang-format` locally.

## Run it on every C++ repository you maintain

A team with several CMake projects starts one run per repository with one `POST /o/{org}/sessions` each, the repository in `resources` and this prompt as `input`. Each run measures that repository's own drift and writes its own workflow, so a project that is already clean gets a check that could run over the whole tree, and one with drift gets the changed-lines check, each with its own pull request.

A key may have at most `max_concurrent` runs in progress at once, four by default; a loop over more C++ repositories than that needs no spacing, since each run past the limit is created with `202` and `status: "queued"` and begins when a slot frees. Send a `request_id`, one UUID per repository, so a retried call returns the run it already started.

## Why run it on Rush?

The reason most C++ projects have a `.clang-format` and no check is the first run: it fails on everything, and the honest options are a giant reformat or giving up. Measuring first and checking only changed lines avoids both, but it takes a current clang-format, a dry run over the tree, a workflow that knows the base commit, and a deliberate failure to prove the gate works. The agent does all of that in a sandbox of its own and keeps the output.

The pull request carries the drift counts and links to a passing and a failing run, so the review is a read of one workflow file. Several repositories can be handled at once, each in its own sandbox with its own pull request.

## Frequently asked questions

### Will this reformat my code?

No. The agent measures the drift and reports it, but changes no C++ file. The new job checks only lines a pull request touches, through `git clang-format` against the base commit, so existing code stays as it is until you choose to reformat it.

### Why pin a clang-format version?

Because each major release changes a few formatting decisions, and a check that moves under contributors' feet gets ignored. The workflow installs one pinned major version from the runner's packages, and the pull request names it so a local setup can match.

### What about the vendored Catch header?

It is excluded twice: the workflow passes only `include`, `src` and `test` sources with `catch.hpp` left out, and a `.clang-format-ignore` file keeps a local `clang-format -i` away from it too. Vendored code is not yours to format.

### How do I know the check actually fails?

The agent proves it on the pull request: a throwaway commit that mis-indents one function in `src/example.cpp` makes the job fail with the diff printed, and that commit is dropped before the pull request is opened. The description links to that run.

## More CMake jobs

- [Add clang-tidy to a CMake C++ Project and Its CI](https://getrush.ai/run/add-clang-tidy/cmake/)
- [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/)

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