> ## Documentation Index
> Fetch the complete documentation index at: https://docs.braintrust.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Google Antigravity

> Trace Antigravity coding sessions to Braintrust and access your Braintrust data through the MCP server

[Google Antigravity](https://antigravity.google/) is Google's coding agent. You can connect it to Braintrust in two ways:

* **Trace Antigravity sessions** to record session, turn, model call, and tool spans in Braintrust.
* **Connect to Braintrust MCP** to work with Braintrust projects, experiments, logs, and other data from Antigravity.

> [!NOTE]
>
> Braintrust tracing for the Antigravity CLI (`agy`) is supported for macOS, Linux, and Windows.

## Trace Antigravity sessions

The [`braintrust-antigravity-tracing` plugin](https://github.com/braintrustdata/braintrust-antigravity-plugin) uses `bt` to trace your Antigravity sessions to Braintrust.

### Set up tracing

> [!NOTE]
>
> If `braintrust-antigravity-tracing` is already installed, follow [Update the tracing plugin](#update-the-tracing-plugin).

**1. Install Antigravity**

If you haven't already, install the [Antigravity CLI](https://antigravity.google/product/antigravity-cli). Make sure its `agy` command is available in your terminal.

**2. Install and authenticate bt**

Follow the [`bt` CLI quickstart](https://docs.braintrust.dev/reference/cli/quickstart) to install `bt`, authenticate, and set your active context.

**3. Enable tracing**

Before starting Antigravity, run this command in a terminal:

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
bt trace enable antigravity --project <your-project>
```

This command:

* Installs (or updates) and enables [`braintrust-antigravity-tracing`](https://github.com/braintrustdata/braintrust-antigravity-plugin) through `agy`.
* Writes `~/.gemini/config/braintrust.json`, which records whether tracing is enabled and which project receives traces.

The tracing file stores settings, not credentials. These settings apply across projects during normal sessions.

For more information, see [`bt trace enable`](https://docs.braintrust.dev/reference/cli/trace#bt-trace-enable).

**4. Restart Antigravity**

Restart Antigravity so it loads the plugin and tracing settings.

**5. Log a test trace**

Ask Antigravity to do something simple in an `agy` session. When the session finishes, open your Braintrust project and confirm that the trace appears on the [\*\* Logs\*\*](https://www.braintrust.dev/app/~/logs) page.

### What Braintrust traces

Antigravity traces in Braintrust include:

* Session spans with conversation identifiers, available workspace and model metadata, and Git repository metadata when available.
* Turn spans with prompts and final responses.
* Model call spans reconstructed from the session transcript, with conversation input, response output, and available token metrics.
* Tool spans with available inputs, outputs, approval outcomes, and errors.

With `bt` v0.19.3 or later, session spans also include the local username when available.

Every span records its origin as `braintrust.plugin.antigravity`, along with versions in `context.span_origin`: the plugin version in `version`, the `bt` version in `bt.version`, and the Antigravity version in `antigravity.version`. These versions are captured when each span is created, and unknown versions are `null`. Each turn span and every span under it records the turn's span ID in `metadata.turn_span_id`. Model inputs are reconstructed from transcripts rather than captured as raw provider requests. Imported sessions do not establish exact historical model-call latency.

### Common workflows

> [accordion] Change saved tracing settings
>
> To change the saved destination, profile, or organization, rerun [`bt trace enable antigravity`](https://docs.braintrust.dev/reference/cli/trace#bt-trace-enable) with the corresponding options. Running [`bt switch`](https://docs.braintrust.dev/reference/cli/switch) does not change the saved tracing configuration.
>
> To add root-span metadata, pass `--additional-metadata '<JSON>'` to `bt trace enable` for future sessions. Standard session metadata takes precedence when keys conflict.
>
> With `bt` v0.19.3 or later, pass `--tag ci --tag release-validation` to `bt trace enable` to [tag session spans](https://docs.braintrust.dev/reference/cli/trace.md#tag-traces).

> [accordion] Trace a saved Antigravity session
>
> Antigravity stores session transcripts locally. Use [`bt trace import`](https://docs.braintrust.dev/reference/cli/trace#bt-trace-import) with `antigravity` and the conversation ID to import a past session, even if tracing was not enabled when it ran.
>
> You can also attach an imported session to an existing span or experiment.

> [accordion] Resume an Antigravity session
>
> When you resume an Antigravity session, new turns are added to its existing Braintrust trace.

> [accordion] Stop tracing Antigravity sessions
>
> Use [`bt trace disable antigravity`](https://docs.braintrust.dev/reference/cli/trace#bt-trace-disable) to uninstall the tracing plugin and remove its tracing configuration. Saved `bt` profiles and credentials are preserved. Restart Antigravity afterward.

### Update the tracing plugin

> [!NOTE]
>
> If `~/.gemini/config/hooks.json` contains a `braintrust-antigravity-tracing` entry, use "Migrate from a manual hook registration" below instead of the routine update steps.

> [accordion] Migrate from a manual hook registration
>
> Record the profile, organization, project, metadata, tags, and custom settings you want to preserve from `~/.gemini/config/braintrust.json` (or the file your `BRAINTRUST_DAEMON_CONFIG` or `BT_DAEMON_CONFIG` override points to). Then follow the [CLI migration guide](https://docs.braintrust.dev/reference/cli/migrate.md) to update `bt` and complete the applicable migrations.
>
> Run this command with the profile, organization, and project you recorded:
>
> ```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
> bt trace enable antigravity \
>   --profile <profile> \
>   --org <organization> \
>   --project <your-project>
> ```
>
> The command installs the plugin and removes the legacy hook entry. Other hook registrations are preserved. Unlike `bt trace update`, it rewrites your tracing settings.
>
> Compare the tracing file with the settings you recorded and restore any custom values. `route.flush_mode` resets to `fire_and_forget`, so restore its previous value if you customized it.
>
> Restart Antigravity, run a short `agy` session, and confirm that its trace appears on the [\*\* Logs\*\*](https://www.braintrust.dev/app/~/logs) page in the intended Braintrust project.

For routine updates, follow these steps:

**1. Update bt**

Follow the [CLI migration guide](https://docs.braintrust.dev/reference/cli/migrate.md) to update `bt` to the latest version and complete the applicable migrations.

**2. Update the tracing plugin**

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
bt trace update antigravity
```

[`bt trace update`](https://docs.braintrust.dev/reference/cli/trace#bt-trace-update) updates the installed plugin without changing your saved tracing configuration.

**3. Restart and verify Antigravity**

Restart Antigravity, run a short `agy` session, and confirm that its trace appears on the [\*\* Logs\*\*](https://www.braintrust.dev/app/~/logs) page in the intended Braintrust project.

### Troubleshooting tracing

First, run `bt trace doctor antigravity`. Then, review the following:

> [accordion] The tracing plugin is missing or disabled
>
> Run `bt trace enable antigravity --project <your-project>` to install and enable the plugin. Restart Antigravity afterward.
>
> The doctor report checks tracing settings and authentication, not whether Antigravity loaded the plugin's hooks.

> [accordion] Traces do not appear after setup
>
> If Antigravity was running when its plugin or configuration changed, restart it. Confirm that `bt` is on the `PATH` of the environment that launches `agy`.
>
> Run `bt trace doctor antigravity` and confirm that tracing is enabled and routed to the intended project.
>
> If authentication succeeds but traces do not appear, confirm that your account has [permission to write logs to the selected project](https://docs.braintrust.dev/reference/cli/trace.md#project-log-permissions).
>
> For authentication, tracing destination, or endpoint problems, see [`bt trace` troubleshooting](https://docs.braintrust.dev/reference/cli/trace#troubleshooting) and the [CLI migration troubleshooting guide](https://docs.braintrust.dev/reference/cli/migrate.md#troubleshooting).
>
> Tracing failures do not interrupt the Antigravity session.

> [accordion] Antigravity uses an unexpected configuration directory
>
> Tracing settings are saved in `~/.gemini/config/braintrust.json`. To use a different file, set `BRAINTRUST_DAEMON_CONFIG` (`BT_DAEMON_CONFIG` in `bt` v0.25.0 and earlier) to its path before both running `bt trace enable antigravity` and launching Antigravity.

> [accordion] Traces use unexpected settings
>
> For normal sessions, the integration does not use `TRACE_TO_BRAINTRUST`, `BRAINTRUST_PROJECT`, or `BRAINTRUST_ADDITIONAL_METADATA` from the agent's environment to override the saved tracing settings.
>
> For environment variables accepted by the `bt` commands themselves, see [`bt trace`](https://docs.braintrust.dev/reference/cli/trace).

## Connect to Braintrust MCP

The Braintrust MCP server lets Antigravity query and update Braintrust data. MCP is configured independently from the tracing plugin.

**1. Choose authentication**

> [tab] OAuth (recommended)
>
> Use OAuth when your client supports it. Your client opens a Braintrust authorization page where you sign in and approve access. The server acts with the permissions of the account you sign in with.
>
> * No Braintrust API key required
> * No OAuth client ID or client secret to configure
>
> The server implements OAuth 2.0 with dynamic client registration and publishes its metadata at `/.well-known/oauth-authorization-server` on the same host as your MCP endpoint (see next step), so a client can register itself.

> [tab] API key
>
> Use an API key for clients without OAuth support or for programmatic connections. The server acts with the permissions of the account the key belongs to.
>
> 1. Create a key in \*\* Settings\*\* > [\*\* API keys\*\*](https://www.braintrust.dev/app/~/configuration/api-keys).
> 2. Configure your client to send this header on every request, replacing `YOUR_BRAINTRUST_API_KEY` with your key:
>
>    ```text theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
>    Authorization: Bearer YOUR_BRAINTRUST_API_KEY
>    ```

> [!NOTE]
>
> Your [`bt login`](https://docs.braintrust.dev/reference/cli/login) doesn't authenticate the MCP server.

**2. Choose your endpoint**

Use the endpoint for your organization's [data plane region](https://docs.braintrust.dev/admin/organizations.md#data-plane-region):

| Region | MCP endpoint |
| - | - |
| US | `https://api.braintrust.dev/mcp` |
| EU | `https://api-eu.braintrust.dev/mcp` |

Other connection details:

* **Self-hosted:** Copy the **MCP URL** from \*\* Settings\*\* > [\*\* Data plane\*\*](https://www.braintrust.dev/app/~/configuration/data-plane). This is your Braintrust API URL with `/mcp` appended.
* **Transport:** If your client asks you to choose a transport, choose HTTP (also called streamable HTTP). SSE-only clients can't connect.

**3. Add the server to Antigravity**

Follow the [Antigravity guide](https://antigravity.google/docs/mcp#getting-started-by-surface) to add the remote server.

**4. Verify the connection**

To verify the connection, ask Antigravity to list your recent Braintrust projects. If it can't connect, see [Braintrust MCP troubleshooting](https://docs.braintrust.dev/integrations/developer-tools/mcp.md#troubleshooting).

**5. Start using Braintrust tools**

Antigravity can query logs, compare experiments, work with datasets, and use other Braintrust tools. For example:

* "Show me my recent Braintrust experiments."
* "Query the last 10 logged requests with errors."
* "Compare accuracy scores between my two latest experiments."

See [what the Braintrust MCP can do](https://docs.braintrust.dev/integrations/developer-tools/mcp.md#what-the-mcp-can-do) for more workflows and example prompts.

## Next steps

* **Learn the CLI**: See the full [`bt trace` reference](https://docs.braintrust.dev/reference/cli/trace).
* **Run evaluations**: Follow the [evaluation guide](https://docs.braintrust.dev/evaluate/run-evaluations.md).
* **Explore MCP tools**: See the [Braintrust MCP tool reference](https://docs.braintrust.dev/integrations/developer-tools/mcp.md#tools).
* **Browse the source**: View the [coding-agent plugins repository](https://github.com/braintrustdata/braintrust-coding-agent-plugins).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.