Skip to content

tweak grok readme #63

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Andrew Kent (realark) merged 1 commit into from
Sep 9, 2026
Merged

tweak grok readme #63

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
49 changes: 18 additions & 31 deletions src/plugins/grok/content/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,47 +1,34 @@
# Braintrust tracing for Grok

> **This repository is generated.** It is built from
> [braintrustdata/braintrust-coding-agent-plugins](https://github.com/braintrustdata/braintrust-coding-agent-plugins).
> Don't edit files here — make changes and file issues in that repository, and they
> will be rebuilt into this one.

Trace Grok coding sessions in Braintrust.

## Quickstart

### Prerequisites

- Grok CLI 1.0.13
- A recent `bt` CLI with `bt trace enable grok`
- Braintrust authentication configured in `bt`
- macOS or Linux with Bash
Prerequisites:

### 1. Install the plugin
- The latest [Grok CLI](https://grok.com/build)
- The latest [Braintrust CLI (`bt`)](https://www.braintrust.dev/docs/reference/cli/quickstart)
Comment on lines +14 to +15

@chatgpt-codex-connector chatgpt-codex-connector Bot Sep 9, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Restore the Bash platform prerequisite

On Windows or any environment without Bash, this shortened prerequisite list now lets users proceed even though every installed Grok hook executes bash "${GROK_PLUGIN_ROOT}/hooks/forward.sh" and the forwarder itself uses Bash syntax. Setup may succeed while every hook then fails and no traces are reported; retain the macOS/Linux-with-Bash requirement or provide a Windows-compatible launcher.

AGENTS.md reference: AGENTS.md:L21-L23

Useful? React with 👍 / 👎.


The published plugin lives at
[`braintrustdata/braintrust-grok-plugin`](https://github.com/braintrustdata/braintrust-grok-plugin).
Install:

```bash
grok plugin install braintrustdata/braintrust-grok-plugin --trust
grok plugin enable trace-grok
bt login --profile myprofile
bt trace --profile myprofile -p my-coding-agent-project enable grok
```

`--trust` allows Grok to run the plugin's tracing hooks. Review the repository
before installing if required by your security policy.

### 2. Enable Braintrust tracing

```bash
bt trace enable grok
```

This saves a non-secret Braintrust destination, updates the published plugin
when necessary, and enables it. The command is safe to repeat.

If Grok was already open during installation or an update, activate the new
hooks in that session:

```text
/reload-plugins
```
This causes `grok` sessions to report to your configured project.

New Grok sessions load the plugin automatically. Start Grok normally and use it
as usual; completed turns will appear in your configured Braintrust project.
> **Note:** Due to a bug in the Grok CLI, you must run `/reload-plugins` at the
> start of each session for traces to be reported. You can use
> `alias grok="grok /reload-plugins"` until the
> [issue is resolved](https://github.com/xai-org/plugin-marketplace/issues/236).

## What is captured

Expand All @@ -68,8 +55,8 @@ native boundaries for every model call. As a result:
- token and usage totals are accurate at the **turn** level, but are not
available for each individual LLM call; the turn aggregate is also attached
to the final reconstructed LLM span and labeled as turn-level usage;
- exact model input is available only for the first reconstructed LLM when the
system prompt and first user message can be recovered;
- exact model input is available only for the first reconstructed LLM span when
the system prompt and first user message can be recovered;
- LLM boundaries are reconstructed from Grok stream timing and may not match
provider-side spans exactly;
- permission, compaction, and subagent activity do not receive dedicated span
Expand Down
Loading