# Add pre-commit Hooks to a CMake C++ Project

Yes. An agent adds a pre-commit config that runs the same clang-format and cmake-format versions your CI enforces, proves it on every file, and opens a PR.

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

## What the agent does

The agent reads what CI enforces so the hooks match it exactly. In a library laid out like fmtlib/fmt, `.github/workflows/lint.yml` runs on every pull request with two jobs: `clang-format` installs `clang-format-21` from apt.llvm.org using the key in `support/llvm-snapshot.gpg.key`, runs it with `-style=file -fallback-style=none` over every `.h` and `.cc` under `include` and `src`, and fails on `git diff --exit-code`; `cmake-format` installs `cmakelang==0.6.13` from `support/cmake-format-requirements.txt` with `--require-hashes` and formats every `CMakeLists.txt` and `.cmake` file the same way. `.clang-format` is Google style with a handful of overrides, `.cmake-format` sets `separate_ctrl_name_with_space`, and `.clang-tidy` enables one `modernize` check. `CONTRIBUTING.md` points at the Google C++ style guide with two exceptions. The other workflows build on Linux, macOS and Windows, fuzz, run CodeQL and build the docs. There is no `.pre-commit-config.yaml`, so a contributor learns about a formatting problem from CI rather than at commit time.

The config the agent writes uses two hooks pinned to the versions CI runs. The `clang-format` hook comes from `pre-commit/mirrors-clang-format` at the tag for major 21, with a `files` pattern limited to `.h` and `.cc` under `include/` and `src/`, so the hook touches exactly the files `lint.yml` does and never reformats the `test/` tree, which CI does not check. The `cmake-format` hook comes from `cheshirekow/cmake-format-precommit` at the tag matching `cmakelang==0.6.13`, over `CMakeLists.txt` and `.cmake` files. Both hooks run in `pre-commit`'s own isolated environments, so a contributor needs no LLVM apt repository or Python requirements file installed by hand.

The agent runs `pre-commit run --all-files` in its sandbox. Because the pinned versions are the ones CI already passes with, the expected result is no change; a file that does change means the pin or the file pattern is off, and the agent corrects the config rather than committing a reformat. The general hooks from `pre-commit/pre-commit-hooks`, such as trailing whitespace and end-of-file fixes, are tried the same way and kept only when they are clean across the repository, so the pull request never arrives with a sweep of unrelated whitespace edits.

It adds a short section to `CONTRIBUTING.md` with the two commands to install the hooks, runs `cmake -S . -B build` and a build of the library target once to confirm nothing it touched affects the build, and opens the pull request. `lint.yml` stays as it is: CI remains the authority, and the hooks are the same checks moved earlier.

## Start it with one API call

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

```json
{
  "agent": "claude",
  "input": "Add pre-commit hooks to this CMake C++ project. Read .clang-format, .clang-tidy, .cmake-format, CONTRIBUTING.md, CMakeLists.txt, the requirements files under support/ and every file under .github/workflows first. Write .pre-commit-config.yaml with a clang-format hook pinned to the same major version the lint workflow installs and a files pattern limited to the directories and extensions that workflow formats, and a cmake-format hook pinned to the cmakelang version the requirements file pins, over CMakeLists.txt and .cmake files. Try the standard pre-commit-hooks and keep only those that are clean across the repository. Run pre-commit run --all-files and fix the config, not the files, if anything changes. Add an install section to CONTRIBUTING.md, configure and build the library once to confirm the tree still builds, leave the lint workflow unchanged, and open a pull request that lists the hook versions and the result of the all-files run.",
  "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

The pull request adds `.pre-commit-config.yaml` and a few lines in `CONTRIBUTING.md`, and changes no source or CMake file. Its description lists each hook with the version it is pinned to and the CI step it mirrors, the general hooks that were kept and the ones left out with the reason, the output of `pre-commit run --all-files`, and the configure and build result from the sandbox.

Once merged, a contributor who runs `pre-commit install` gets the same clang-format and cmake-format verdict at commit time that `lint.yml` would give on the pull request, and a change that the hook reformats never reaches CI red.

Before merging, a reviewer confirms the two pins match `lint.yml` and `support/cmake-format-requirements.txt`, decides whether the `test/` tree should be formatted too now that a hook makes it cheap, and checks that the install instructions fit the contributing guide's tone.

## Run it on every new repository

An organisation with several C++ libraries sends this body once per repository from its own server, each a `POST /o/{org}/sessions` with that repository in `resources` and a `request_id` that is a UUID v5 of the repository's full name, so a retried call returns the run already started. Each run reads its own lint workflow: a repository that runs clang-tidy in CI gets a clang-tidy hook as well, and one whose formatter version is unpinned gets a pull request that names the version it chose and why.

Once the hooks exist, an automation on the Project with a `github` trigger on `pull_request.opened` and the prompt "if the lint workflow failed on this pull request, run the pre-commit hooks on its diff and comment with the files and the hook that would have fixed them" starts one run per pull request. The trigger adds the pull request after the prompt, and the run comments without pushing.

## Why run it on Rush?

A pre-commit config that pins a different formatter version from CI produces commits that pass locally and fail on the pull request. The agent reads the versions out of the workflow and the hashed requirements file and runs the hooks over every file in its own sandbox, so the first proof that they agree with CI is in the pull request rather than in the next contributor's experience.

The all-files run, the configure and the build stay with the run as the record. A team with many libraries starts one run per repository at once, each in its own sandbox with its own hook environments.

## Frequently asked questions

### Why mirror the CI versions exactly?

clang-format output changes between majors, and cmake-format between releases. A hook on a different version reformats code that CI accepts, or accepts code that CI rejects. Pinning the hook to the major `lint.yml` installs and the `cmakelang` version the requirements file hashes keeps both verdicts the same.

### Will it reformat the whole repository?

No. The hooks run only over the paths CI already checks, and the pinned versions are the ones that tree already passes with. The all-files run is expected to change nothing; if it does, the agent fixes the config and says so in the pull request.

### Does CI change?

No. `lint.yml` keeps its two jobs and remains the check that gates merges. The hooks move the same checks to commit time for contributors who install them.

### Can clang-tidy be a hook too?

It can, but it needs a compile database and is slow on every commit, and the repository's CI does not run it. The pull request mentions it as a later addition rather than including it.

## More CMake jobs

- [Add a GitHub Release Workflow With CPack Packages to a CMake Project](https://getrush.ai/run/add-release-workflow/cmake/)
- [Add AddressSanitizer and UBSan CI to a CMake Project](https://getrush.ai/run/add-sanitizer-ci/cmake/)
- [Fix "Compatibility with CMake < 3.5 Has Been Removed from CMake" After a CMake 4 Upgrade](https://getrush.ai/run/fix-compatibility-with-cmake-3-5-has-been-removed/cmake/)

## The same job on other stacks

- [Add dbt-checkpoint Pre-commit Hooks to a dbt Project](https://getrush.ai/run/add-pre-commit-hooks/dbt/)
- [Add Pre-commit Hooks to a Kubernetes Manifest Repository](https://getrush.ai/run/add-pre-commit-hooks/kubernetes/)
- [Add Pre-commit Hooks to a Python Project](https://getrush.ai/run/add-pre-commit-hooks/python/)

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