# Generate compile_commands.json for a Bazel C++ Project

Yes. An agent adds a compile commands extractor to your Bazel C++ workspace, generates compile_commands.json, checks it with clangd, and opens a PR with the setup.

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

## 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`

```json
{
  "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"
    }
  ]
}
```

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

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.

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

- [Add Code Coverage to CI for a Bazel Repository](https://getrush.ai/run/add-coverage-to-ci/bazel/)
- [Set Up GitHub Actions CI for a Bazel Repository](https://getrush.ai/run/add-github-actions-ci/bazel/)
- [Migrate a Bazel WORKSPACE to Bzlmod](https://getrush.ai/run/migrate-to-bzlmod/bazel/)

## More jobs like this: Hand off a long task

- [Add the Mandatory Compliance Webhooks to a Shopify App](https://getrush.ai/run/add-compliance-webhooks/shopify-app/)
- [Refactor a Pulumi Program Into Component Resources](https://getrush.ai/run/add-component-resources/pulumi/)
- [Add Compose Profiles for Optional Services](https://getrush.ai/run/add-compose-profiles/docker-compose/)

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