Skip to main content
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: 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

1

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. 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.
2

Run the install command

Run the command as the developer who uses Grok Build:
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.
3

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.

​
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.

​
Content categories

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.

​
Metrics enabled

Once reporting, the plugin feeds:

​
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:
Uninstalling doesn’t revoke the API key. Delete it under Grok Build plugin API keys to stop every install that uses it.

​
Troubleshooting

The hook requires Node.js 18 or later. Install it and re-run the command, or pass NODE_BIN=/path/to/node before bash.
  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
Link the install from the Members page. 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.
If a name is on People we’re receiving data from, the install worked. Dashboards update about hourly; that list is the live check.

​
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.
Last modified on October 17, 2026