What the agent does
The agent first works out which directory is the Bazel workspace, since compile_commands.json belongs at a workspace root and a repository can hold many. In a repository like bazelbuild/examples there are forty MODULE.bazel files, and the C++ tutorial alone has three, one per stage. cpp-tutorial/stage3 is a complete workspace: its MODULE.bazel is a single line, bazel_dep(name = "rules_cc", version = "0.0.17"); main/BUILD declares a cc_library named hello-greet and a cc_binary named hello-world that depends on it and on //lib:hello-time; lib/BUILD declares that library with visibility limited to //main:__pkg__. The sources include each other by workspace-relative path, lib/hello-time.h and main/hello-greet.h, which is exactly what an editor cannot resolve without the compiler's include flags. The stage has no .bazelrc, no .bazelversion and no root BUILD file, and the repository's root .gitignore already ignores bazel-* and *MODULE.bazel.lock.
It adds the extractor the way its README prescribes for a workspace on bzlmod. Hedron's compile commands extractor is installed with bazel_dep(name = "hedron_compile_commands", dev_dependency = True) followed by a git_override that names the Git remote and one commit, and the README asks for the latest commit on its main branch instead of a release. The agent reads that branch, pins the commit it finds, and writes both stanzas into cpp-tutorial/stage3/MODULE.bazel under the rules_cc line. Marking it a development dependency means a module that depends on this one does not inherit the tool.
Then it generates the file and proves an editor can use it. In its sandbox the agent installs Bazelisk, a C++ compiler and clangd, runs bazel build //... in the stage to confirm the workspace builds on the Bazel release Bazelisk selects, and runs bazel run @hedron_compile_commands//:refresh_all, the README's path for a workspace where every target builds with no extra flags. That writes compile_commands.json at the workspace root and an external link beside it that points into Bazel's output base. The agent opens the JSON, checks there is an entry for main/hello-world.cc, main/hello-greet.cc and lib/hello-time.cc and for the headers, and runs clangd --check=main/hello-world.cc, which parses the file with those commands and reports whether the two workspace-relative includes resolved.
The generated file is not committed, because its entries describe one machine's toolchain and output paths. The agent adds a .gitignore in the stage that lists /compile_commands.json, /external and clangd's /.cache/, and writes a short section in the stage's README.md: the one command to run after a BUILD change, and the three clangd arguments the extractor's README gives, --header-insertion=never, --compile-commands-dir and --query-driver=**, with the directory set to this stage because the workspace is a subdirectory of the repository. renovate.json at the root already enables the bazel-module manager, so the pull request points out that the pinned commit is the one line a dependency bot would need to keep current, and does not claim to have tested that.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "Set up compile_commands.json generation for the Bazel C++ workspace in this repository, so clangd can resolve includes. Find the workspace root first: read the MODULE.bazel, every BUILD file, the .cc and .h files, any .bazelrc and .bazelversion, the root .gitignore and renovate.json. Add Hedron's compile commands extractor to MODULE.bazel as a dev dependency with a git_override pinned to the latest commit on its main branch, following its README for bzlmod. In your sandbox install Bazelisk, a C++ compiler and clangd, run bazel build //... and report the Bazel version used, then run bazel run @hedron_compile_commands//:refresh_all. Confirm compile_commands.json has an entry for every source and header in the workspace, and run clangd --check on the file with the main function and quote its output. Do not commit the generated file: add a .gitignore in the workspace for compile_commands.json, the external link and clangd's cache. Add a README section with the refresh command and the clangd arguments, with --compile-commands-dir pointing at this workspace. Open a pull request that lists the commands you ran, their results and the commit you pinned.",
"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
A pull request with three small changes in the workspace: two stanzas added to MODULE.bazel, a new .gitignore, and a README section. Its description records the Bazel version Bazelisk chose, the result of bazel build //..., the number of entries the extractor wrote and for which files, and the output of clangd --check, so a reader can see that the includes resolved and not only that a file was produced.
A reviewer checks that the pinned commit is recent, that the extractor is a development dependency, and that nothing generated was committed. After merging, each developer runs the refresh command once and again whenever BUILD files change, and points their editor's clangd at the workspace directory; the pull request says which editor settings that means and leaves personal editor files out of the repository.
Run it on every terminal hand-off
A developer who has just opened a .cc file and found every project include underlined sends this body from the terminal with the repository in resources, and keeps working. The run reads the real MODULE.bazel and BUILD files, so the extractor is installed for the module system the workspace uses and the refresh command is the one that matches its targets.
Put a request_id, a UUID, in the body so a retried start returns the run that is already going. When the turn ends, GET /o/{org}/sessions/{id} names the pull request. A follow-up to the same session can ask for a refresh_compile_commands target limited to a few packages in a larger workspace, or for the build flags a team always passes to be forwarded to the extractor.
The use case this job follows, with its automation and trigger: Hand off a long task.
Why run it on Rush?
This setup fails quietly: the JSON gets written, the editor still shows errors, and the cause is a toolchain flag or a missing link nobody thinks to look at. The agent installs the toolchain in its own sandbox, generates the file, and runs clangd against it, and the commands and their output stay in the run's record, so the pull request carries evidence that an include resolved.
The request carries over to a workspace still on a WORKSPACE file, where the extractor is fetched with http_archive and its setup macros, to one that builds only with a --config flag, and to a repository with several workspaces that each need their own file. Each run reads the workspace in front of it and reports the Bazel version and targets it actually built.
Frequently asked questions
Why is compile_commands.json not committed?
Its entries hold the compiler invocation Bazel used on one machine, including paths under that machine's output base. Another developer's paths differ, so the file is generated locally with one command and ignored by Git, along with the external link the tool creates.
Do I have to rerun the extractor after every change?
Only when the build graph changes: a new target, a new dependency, different copts. Editing code inside existing files needs no refresh. The README section the run adds says which command to run and when.
Why git_override instead of a version from the Bazel registry?
That is the installation its own README gives for bzlmod: a development bazel_dep plus a git_override naming the repository and a commit, with advice to track the latest commit. The agent follows the README and records the commit it pinned in the pull request.
Does this work if my targets need extra flags to build?
Yes, with one change. The extractor's README says to pass the same flags after a -- separator when running the refresh target, or to define a refresh_compile_commands target that names your targets and their flags. The run picks the plain command only when every target builds without extras, as in a tutorial workspace.
More Bazel jobs
More jobs like this: Hand off a long task
- Add the Mandatory Compliance Webhooks to a Shopify App (Shopify app)
- Refactor a Pulumi Program Into Component Resources (Pulumi)
- Add Compose Profiles for Optional Services (Docker Compose)