Skip to main content
Grok is xAI’s coding agent. You can connect it to Braintrust in two ways:
  • Trace Grok 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 Grok.
This guide covers the Grok CLI on macOS and Linux. The tracing hooks require Bash.

​
Trace Grok sessions

The trace-grok plugin passes your interactions with Grok to bt, which in turn uses a background process to build and deliver the trace to Braintrust. Grok continues to communicate directly with its model provider, and tracing failures do not stop your Grok session.

​
Set up tracing

If trace-grok is already installed, follow Update the tracing plugin.
1

Install Grok

If you haven’t already, install the Grok CLI.
2

Install and authenticate bt

Follow the bt CLI quickstart to install bt v0.19.3 or later, authenticate, and set your active context.
3

Enable tracing

If you installed trace-grok from a local directory or a different repository, this command uninstalls that version and installs Braintrust’s published plugin. Save a copy of any changes you made to the plugin’s code or hooks before continuing.
Before starting Grok, run this command in a terminal:
This command:
  • Installs (or updates), trusts, and enables trace-grok. Trust applies to the plugin’s executable hooks, not to your project folders.
  • Writes ~/.grok/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.
4

Load the tracing hooks

Start Grok and run /reload-plugins inside the session before sending your first prompt.
Due to a bug in the Grok CLI, you must run /reload-plugins at the start of each session for traces to be reported, even after restarting. To automate this, alias Grok to run the command on launch with alias grok="grok /reload-plugins" until the issue is resolved.
5

Log a test trace

Ask Grok to do something simple. When the session finishes, open your Braintrust project and confirm that the trace appears on the Logs page.

​
What Braintrust traces

Grok traces in Braintrust include:
  • Session spans with the session ID, local username, available workspace and permission settings, Grok and plugin versions, and Git repository metadata when available.
  • Turn spans with prompts, visible assistant responses, and available usage metrics.
  • Reconstructed model call spans with available responses and reasoning. The first model call can also include the recovered system prompt and first user message.
  • Tool spans with available inputs, outputs, timing, outcomes, and errors.
Every span records its origin as braintrust.plugin.grok. Grok does not expose complete provider requests or native boundaries for every model call. Usage belongs to the whole turn, not individual model calls. The turn’s usage is also attached to the final reconstructed model span with usage_scope: "turn". Raw cost_usd_ticks values are not converted to estimated dollar costs.

​
Common workflows

To change the saved destination, profile, or organization, rerun bt trace enable grok with the corresponding options. Running bt 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.
When you resume a Grok session, new turns are added to its existing Braintrust trace. Run /reload-plugins in the resumed session before continuing.
Use bt trace disable grok to uninstall the published tracing plugin and remove its tracing configuration. Saved bt profiles and credentials are preserved. Restart Grok afterward.The command leaves local or custom plugins with the same name installed.

​
Update the tracing plugin

To update the plugin, follow these steps:
1

Update bt

Follow the CLI migration guide to update bt to the latest version and complete the applicable migrations.
2

Update the tracing plugin

bt trace update updates the installed plugin without changing your saved tracing configuration. The command requires the published Braintrust plugin and does not replace local or custom installations.
3

Restart and verify Grok

Restart Grok and run /reload-plugins. Run a short session and confirm that its trace appears on the Logs page in the intended Braintrust project.

​
Troubleshooting tracing

First, run bt trace doctor grok. Then, review the following:
Run grok plugin list --json and confirm that trace-grok is installed and enabled. If it is missing or broken, run:
Run /reload-plugins in Grok afterward. The doctor report checks tracing settings and authentication, not whether Grok loaded the hooks.
Run /reload-plugins in the active Grok session. Confirm that bt is available in the environment that launches Grok. If necessary, set BT_BIN to the executable’s path.Run bt trace doctor grok 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.For authentication, tracing destination, or endpoint problems, see bt trace troubleshooting and the CLI migration troubleshooting guide.Tracing failures do not interrupt the Grok session.
The tracing file is ~/.grok/braintrust.json. An explicit BT_DAEMON_CONFIG override changes the tracing file path. If you use it, supply the same path when enabling tracing and launching Grok.
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.

​
Connect to Braintrust MCP

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

​
Set up the MCP server

1

Install Grok

If you haven’t already, install the Grok CLI.
2

Add the Braintrust MCP server

From the terminal, configure Grok’s connection to the Braintrust MCP server:
Grok stores this configuration in ~/.grok/config.toml. To configure only the current project, add --scope project to write .grok/config.toml instead. See Grok’s MCP documentation for scope and configuration details.See Authentication for API-key setup and Endpoints for EU and self-hosted URLs.
3

Authenticate

In Grok, enter /mcps, select the Braintrust MCP server, and press i to start OAuth authentication. Complete the sign-in in your browser.MCP authentication is separate from bt login, which authenticates the CLI and tracing integration.
4

Verify the connection

Run grok mcp doctor braintrust to check the connection. In Grok, ask it to list your recent Braintrust projects and confirm that it uses the Braintrust MCP server.

​
Use MCP tools

Once connected, Grok 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 for more workflows and example prompts.

​
Troubleshooting MCP

Run grok mcp list to confirm that the Braintrust server is registered. Use /mcps in Grok to enable the server or refresh it after configuration changes.If Grok loads an unexpected server, run grok inspect to see its configuration source. Grok can also load MCP definitions from Claude Code and Cursor configurations. See Grok’s MCP documentation for configuration precedence.
Run grok mcp doctor braintrust to diagnose the connection. To authenticate again, enter /mcps in Grok, select the Braintrust MCP server, and press i to start the OAuth flow.For authentication methods, regional and self-hosted endpoints, and network requirements, see the Braintrust MCP guide.

​
Next steps