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

# Grok Build plugin

> Send Grok Build session, prompt, and tool telemetry to Weave with a local hook

The Weave Grok Build plugin is a local hook that Grok Build runs on its lifecycle events. The hook sends session, prompt, tool-call, and file-edit telemetry to Weave from each developer's machine.

## What's tracked

The hook registers for `SessionStart`, `SessionEnd`, `UserPromptSubmit`, `PreToolUse`, `PostToolUse`, `PostToolUseFailure`, `PermissionDenied`, `Stop`, `StopFailure`, `StopCancelled`, `SubagentStart`, `SubagentStop`, and `PostCompact`. Existing installs pick up newly added events on their own, without reinstalling, unless they use a custom `GROK_HOME`. Re-run the installer for those. Weave stores:

* **Session activity**: session start and end, duration, model, working directory, and git branch and remote
* **Prompts**: prompt submissions and, when prompt bodies are allowed, prompt text for activity classification
* **Replies**: the final assistant reply of each completed turn, when agent messages are allowed. Grok Build only exposes the turn's last message, capped at 32,768 characters, so replies at the cap are skipped for AI skills scoring
* **Tool calls**: tool name, success or failure, model, and, when tool I/O and file paths are both allowed, tool input and the error text of failed calls
* **File edits**: edited file path plus lines added and removed for successful edits
* **Turn outcomes**: completed, failed, and cancelled turns, with the last error type. Error details are stored only when tool I/O is allowed. A subagent's `SubagentStop` counts as a completed turn of the subagent's own session.
* **Permission denials**: each tool call that Grok Build's permission system denied, counted once per session. Denied calls aren't stored as tool calls, because the tool never ran.
* **Subagents and compactions**: how many subagents each session started and how many times its context was compacted. Subagents run as their own Grok Build sessions, which Weave flags with the subagent type. Grok Build doesn't say which session started a subagent, so a parent session doesn't show its subagents' outcomes.
* **Session context**: permission mode and, when file paths are allowed, the workspace root
* **Install health**: members appear under **People we're receiving data from** once the installer's ping or the first event arrives

Grok Build does not report token usage or cost, so the plugin does not capture either.

## What it unlocks

* **Per-developer, per-session activity**: attribute Grok Build sessions to individual Weave members
* **[AI skills](/reports/ai-skills)**: conversation scoring from Grok Build prompts, final replies, and tool calls
* **Agent observability**: Grok Build tool calls, file edits, subagent counts, and compaction counts appear alongside other agents
* **Agent failure heatmap**: failed Grok Build tool calls appear in the heatmap and its drilldown. A failure is only shown when its error text was captured, so failures are left out when tool I/O or file paths are not allowed.
* **PR linking**: Grok Build sessions link to the pull requests they worked on, matched by session, git branch, and remote. Branch and remote matching needs the `git_context` category allowed by both the install and the organization policy. Git AI line attribution doesn't recognize Grok Build, so Grok Build sessions don't get line-level attribution.

## Prerequisites

* Grok Build installed for the developer who runs the installer
* **Node.js 18 or later** on `PATH`, or set `NODE_BIN` to a Node binary
* `curl`
* macOS or Linux. On Windows, run the installer in WSL.
* A Weave account. Any signed-in member can create a personal install command; a shared key needs an organization admin

## Setup

<Steps>
  <Step title="Create a plugin API key in Weave">
    On **Data**, open the **Grok Build (Plugin)** card (or **Personal plugin setup** → **Grok Build** if you can't manage connections), or go to the [Grok Build plugin configure page](https://app.workweave.ai/grok-build-plugin/configure). Any signed-in member can click **Create my install command**. That command writes telemetry onto their own Weave account, and **Revoke my install command** revokes it, so machines using it stop sending telemetry. Installed hook files and telemetry already sent stay in place. An admin can also click **Create API key** for a shared key that attributes by email. Weave shows the full key once, together with an install command and a downloadable `install.sh`. Keys use the `wgrokkey_` prefix.
  </Step>

  <Step title="Run the install command">
    Run the command as the developer who uses Grok Build:

    ```bash theme={null}
    curl -fsSL 'https://app.workweave.ai/api/grok_build_plugin/plugin/install.sh' | bash -s -- \
      --token 'wgrokkey_...' --endpoint 'https://app.workweave.ai/ingest' \
      --privacy-mode false --prompt-bodies true --agent-messages true \
      --tool-io true --file-paths true --git-context true
    ```

    Weave's modal fills in the real key, endpoint, and the content flags allowed by your organization's policy.

    The installer writes:

    * `~/.grok/hooks/weave-telemetry.js`: the hook runtime
    * `~/.grok/hooks/weave-telemetry.json`: the Grok Build hook registration
    * `~/.weave/grok-build-plugin.json`: the Weave token and content policy

    Set `GROK_HOME` before running the command if Grok Build uses a directory other than `~/.grok`.
  </Step>

  <Step title="Restart Grok Build">
    The installer prints `Verified the Weave telemetry pipe with install_ping.` when Weave received its test event. Restart Grok Build so it loads the new hook, then run a session.
  </Step>
</Steps>

### Member attribution

A personal install command writes every session onto the member who created it, whatever the git email. With a shared key, the hook sends the developer's `git config user.email`. Set `WEAVE_USER_EMAIL` before the developer's first Grok Build session to override it. Once the hook has cached a git email on a machine, later changes to `WEAVE_USER_EMAIL` or `git config` may not take effect. Link installs whose email doesn't match a Weave member from the [Members page](https://app.workweave.ai/members).

## Content categories

| Category | What it controls | Installer flag |
| - | - | - |
| `prompt_bodies` | Text of the prompts you send to Grok Build | `--prompt-bodies` |
| `agent_messages` | Final assistant reply of each turn | `--agent-messages` |
| `tool_io` | Tool input and failed-call error text | `--tool-io` |
| `file_paths` | Working directory and edited file paths | `--file-paths` |
| `git_context` | Git branch and remote | `--git-context` |

Pass `false` to deny a category. `--privacy-mode true` denies all five at once. Weave stores tool input and failed-call error text only when both `tool_io` and `file_paths` are allowed, because tool payloads embed file paths.

The organization's **Telemetry content retention** policy is the floor. The install command's flags are pre-filled from it, and the downloadable `install.sh` re-applies it after your flags, so its flags can only deny more. Weave applies the policy again at ingest before storing rows, so a flag can't bring back a category the policy denies.

### Prompt retention

Claude Code and Cursor hold prompt text until it is scored and then purge it when prompt retention is off. Grok Build has no such hold: when prompt retention is off for the organization or member, Weave drops the prompt text at ingest and stores only prompt metadata.

## Fleet / MDM rollout

1. Create one organization plugin API key.
2. Download `install.sh` from the key modal. It has the key and content flags filled in.
3. Run it in each developer's user context through your MDM, such as a Jamf policy, a Kandji custom script, or an Intune shell script.
4. Link installs that aren't matched to Weave members from the [Members page](https://app.workweave.ai/members).

## Metrics enabled

Once reporting, the plugin feeds:

* **[Conversation prompt quality](/metrics/conversation-prompt-quality)**: prompt-level signals from captured sessions
* **[AI skills](/reports/ai-skills)**: per-conversation scoring

## Cost tracking

Grok Build hooks don't include tokens or cost, so Weave shows no spend for Grok Build.

## Sync frequency

The hook sends each event to Weave as Grok Build fires it. Dashboards update about hourly.

## Uninstall

There is no uninstall flag. Delete the hook and its configuration, then restart Grok Build. If you installed with a custom `GROK_HOME`, set it to the same directory first:

```bash theme={null}
GROK_HOOK_DIR="${GROK_HOME:-$HOME/.grok}/hooks"
rm -f "$GROK_HOOK_DIR/weave-telemetry.js" "$GROK_HOOK_DIR/weave-telemetry.json" ~/.weave/grok-build-plugin.json
```

Uninstalling doesn't revoke the API key. Delete it under **Grok Build plugin API keys** to stop every install that uses it.

## Troubleshooting

<AccordionGroup>
  <Accordion icon="terminal" title="Installer can't find Node">
    The hook requires Node.js 18 or later. Install it and re-run the command, or pass `NODE_BIN=/path/to/node` before `bash`.
  </Accordion>

  <Accordion icon="plug" title="Install finished but Weave shows nothing">
    1. Confirm the installer printed `Verified the Weave telemetry pipe with install_ping.`
    2. Restart Grok Build so it loads `~/.grok/hooks/weave-telemetry.json` (or `$GROK_HOME/hooks/weave-telemetry.json`)
    3. Run a prompt in a new session
    4. Check that the machine can reach the ingest endpoint
  </Accordion>

  <Accordion icon="user" title="Usage is not attributed to a Weave member">
    Link the install from the [Members page](https://app.workweave.ai/members). Changing `git config --global user.email` or `WEAVE_USER_EMAIL` may not change the reported email once the hook has cached one on that machine.
  </Accordion>

  <Accordion icon="heart-pulse" title="How do I know the setup worked?">
    If a name is on **People we're receiving data from**, the install worked. Dashboards update about hourly; that list is the live check.
  </Accordion>
</AccordionGroup>

## Data privacy

The hook only sends what Grok Build passes to it, filtered by your content policy. Weave does not read source files, except to count lines changed by a successful edit on the developer's machine.

## Related integrations

* [Claude Code plugin](/ai-tools/claude-code-plugin): the equivalent per-machine plugin for Claude Code
* [Cursor plugin](/ai-tools/cursor-plugin): the equivalent per-machine plugin for Cursor
* [Codex plugin](/ai-tools/codex-plugin): the equivalent per-machine plugin for Codex
* [Copilot plugin](/ai-tools/copilot-plugin): Copilot Chat's built-in OpenTelemetry export


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