All jobs

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 RushOpens 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 with this body:

{
  "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.

The use case this job follows, with its automation and trigger: Hand off a long task.

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

More jobs like this: Hand off a long task

Keep reading