What the agent does
The agent clones the repository into its own cloud sandbox and reads the build matrix before touching it. In a C++ library like fmtlib/fmt, .github/workflows/linux.yml runs a matrix of g++-4.9, g++-11, clang++-3.6 and clang++-11 in Debug and Release at C++11, with include entries that add g++-13, g++-14 with sanitizers, g++-16 with -freflection, clang++-14 and clang++-20 at standards up to 26, some on ubuntu-24.04 and some with the Ninja generator. Every job configures with -DFMT_DOC=OFF -DFMT_PEDANTIC=ON -DFMT_WERROR=ON, builds with cmake --build . --parallel, and runs ctest. macos.yml builds Debug and Release at C++11, 17, 20 and 23 on macos-15, and windows.yml covers MSVC v142 and v143 plus two MSYS2 jobs. The Linux workflow already caches something: actions/cache keeps ~/apt-cache for the .deb files of old compilers, keyed on the OS, compiler and install line. Nothing caches object files, and CMakeLists.txt never mentions CMAKE_CXX_COMPILER_LAUNCHER.
The one place ccache appears is test/fuzzing/build.sh, which sets CXX="ccache g++" for a local fuzzer build, so the project is not opposed to it. The agent adds it to CI through the launcher variable rather than by wrapping the compiler, because the linux.yml matrix selects CXX and derives CC in a step of its own and the launcher leaves that alone. Each Linux and macOS job gets a step that installs ccache from apt or brew, a step that restores a cache directory keyed on the runner OS, matrix.cxx, matrix.std, matrix.build_type and the hash of include/, src/ and test/, with a restore key that drops the hash so a changed source tree starts warm, and -DCMAKE_CXX_COMPILER_LAUNCHER=ccache on the configure line. A final step runs ccache --show-stats with if: always() so a miss is visible in the log.
Some jobs cannot use it and the agent says which. The g++-4.9 and clang++-3.6 jobs run compilers installed from downloaded .deb files that ccache handles, but the two sanitizer jobs pass -fsanitize through CXXFLAGS, which is part of ccache's hash and so simply caches separately. The MSVC jobs use the Visual Studio generator, where the launcher variable has no effect, so windows.yml is left as it is and the MSYS2 jobs, which use Ninja, get ccache from pacboy. The agent sets CCACHE_COMPILERCHECK=content so a compiler upgraded in place on the runner image invalidates its entries, and CCACHE_MAXSIZE to a value the repository's object output fits in, which it measures.
The proof is two builds in the sandbox with the same configure line as the g++-11 Debug C++17 job: cmake -DCMAKE_CXX_COMPILER_LAUNCHER=ccache -DCMAKE_BUILD_TYPE=Debug -DCMAKE_CXX_STANDARD=17 -DFMT_DOC=OFF -DFMT_PEDANTIC=ON -DFMT_WERROR=ON, a cold build and then a clean rebuild, with ccache --show-stats after each and ctest after the second to show the cached objects link into a passing test run. Those three outputs, the hit count and the cache size, go into the pull request. The agent changes no compiler flag and no CMake option, and FMT_WERROR stays on so a warning ccache might mask by replaying an old object is still a failure the first time.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "Add ccache to this CMake project's GitHub Actions. Read CMakeLists.txt and every workflow under .github/workflows first. For each Linux and macOS job, install ccache, restore a cache keyed on the runner OS, compiler, C++ standard and build type with a source hash and a fallback key, pass -DCMAKE_CXX_COMPILER_LAUNCHER=ccache at configure, and print ccache statistics at the end even on failure. Leave jobs whose generator ignores the launcher unchanged and say which. Change no compiler flag or CMake option. In your sandbox, run one job's exact configure line cold and then again from a clean build directory, and put both ccache statistics outputs and the ctest result in the pull request. Open a pull request.",
"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
What comes back is a pull request on its own branch that changes .github/workflows/linux.yml, .github/workflows/macos.yml and the MSYS2 jobs in .github/workflows/windows.yml, and nothing under include/, src/, test/ or in CMakeLists.txt. The description lists each matrix job with the cache key it will use, the jobs left alone and why, and the two ccache --show-stats outputs from the sandbox: the cold run with every compilation a miss, and the rebuild with the hits, followed by the ctest summary from the rebuilt tree.
The run's record keeps the installation, both builds and the statistics commands with their full output, so a reviewer can confirm the hit rate was measured on this project's sources with this project's flags, not assumed from a template.
Before merging, a reviewer checks that the cache key includes everything that changes object code here, which is why matrix.std, matrix.build_type and CXXFLAGS are all in it, decides whether the actions/cache version pinned by hash in linux.yml should be the one the new steps use too, and watches the first few runs on the pull request itself, since the workflow runs there and the statistics step shows the cache filling.
Run it on every repository
Start this once from a terminal with POST /o/{org}/sessions, this body and the repository in resources. The run carries on in its sandbox after the window closes, and a follow-up through POST /o/{org}/sessions/{id}/messages can add the Windows MSVC jobs with sccache, or change the key scheme, without a second cold start. After the merge, the workflows do the ongoing work on every push and pull request.
A team with several CMake repositories starts one run per repository from a script with the same body, each with its own request_id, a UUID, so a retried start returns the run it already began; the key's webhook_url receives run.completed for each with a session_url from which the handler reads the pull request link.
The use case this job follows, with its automation and trigger: Hand off a long task.
Why run it on Rush?
A compiler cache is worth exactly its hit rate, and the hit rate depends on getting the key right for this matrix: a key without the C++ standard hands a C++11 object to a C++20 job and the build fails late, a key with too much in it never hits. The agent reads the matrix as written, builds the key from the variables that actually vary, and measures a warm rebuild in its sandbox before anyone waits on CI to find out.
Measuring that on a laptop means installing four compilers you do not otherwise use. The sandbox is disposable, the two builds and their statistics stay in the run's record, and several repositories can be done in parallel, each with its own pull request and its own measured numbers.
Frequently asked questions
Will ccache ever make a build wrong?
It hashes the preprocessed source, the compiler and the flags, so a changed header or flag is a miss. The agent sets CCACHE_COMPILERCHECK=content so a compiler replaced under the same path on the runner image invalidates its entries as well, and FMT_WERROR and FMT_PEDANTIC are left on so warnings still fail the build the first time they appear.
Why are the MSVC jobs left out?
Those jobs use the Visual Studio generator through cmake -A, and CMAKE_CXX_COMPILER_LAUNCHER only applies to Makefile and Ninja generators. The MSYS2 jobs do use Ninja and get ccache. MSVC caching with sccache is a different change and can be asked for in a follow-up.
Does this change any flags or what the tests build?
No. The configure lines keep every -D option they had, and the only addition is the launcher variable. The sandbox runs ctest on the rebuilt tree to show the cached objects link and pass as before.
How is the cache kept from growing without bound?
CCACHE_MAXSIZE is set from the size the agent measured for a full build of this project, and the cache action's key includes the source hash, so a stale entry ages out as GitHub evicts unused caches. The statistics step prints the size on every run.
More CMake jobs
More jobs like this: Hand off a long task
- Add Changesets to a TypeScript Library (TypeScript library)
- Add Checkov Scanning to a Terraform Module's CI (Terraform)
- Add Checkstyle to a Maven Build (Maven)