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 with this body:
{
"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"
}
]
}- 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
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.
The use case this job follows, with its automation and trigger: Hand off a long task.
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.