---
title: Grok
description: How ClawMetry observes Grok — where its data lives, the environment variables that move it, what cost data is real, and the traps in its store.
eyebrow: Runtime reference
---

# Grok

Grok Build CLI keeps a global append-only event log plus a per-session directory. It also stages codebase archives for upload to xAI, and ClawMetry surfaces that manifest so you can see what left your machine.

| | |
|---|---|
| **Runtime id** | `grok` |
| **Category** | Terminal coding agent |
| **Vendor** | xAI |
| **Tier** | Paid tier (Starter and up) |
| **Upstream** | [x.ai](https://x.ai) |

## Where the data comes from

ClawMetry reads these locations, in order, and never writes to any of them.

- `~/.grok/logs/unified.jsonl` — global event log, primary token source
- `~/.grok/sessions/<encoded-cwd>/<session-uuid>/summary.json`
- `~/.grok/sessions/<encoded-cwd>/<session-uuid>/events.jsonl`
- `~/.grok/upload_queue/` — staged codebase archives

**Format.** JSONL keyed by `msg` and `sid`; sessions are reconstructed by joining the global log on the session id.

## Environment variables

| Variable | Effect |
|---|---|
| `CLAWMETRY_GROK_HOME` | home override |

See [Environment variables](/docs/config/environment/) for the variables that apply to every runtime.

## Tokens and cost

**Tokens.** From `shell.turn.inference_done` rows: prompt, cached prompt, completion and reasoning tokens.

**Cost.** Derived — the xAI provider is priced in ClawMetry's table and any `grok` model name resolves to it.

:::note Why this section exists
Runtimes differ enormously in what they persist. Rather than showing a plausible number everywhere, ClawMetry reports what the store actually contains and marks the rest unknown. A cost of `$0.00` and a cost of *unknown* mean different things, and the dashboard keeps them different.
:::

## Sub-agents and delegation

The `task` tool writes `subagents/<id>/meta.json` in the parent session directory; that file is the authoritative parent-child link. The child is also a top-level session with `session_kind="subagent"` but carries no parent id of its own.

## Things worth knowing

- The upload queue is worth watching: `repo_state.upload.enqueued` records the manifest of what the CLI stages for xAI's trace bucket.
- A missing `output.json` for a sub-agent is honest silence — it is only written on success with non-empty output — never an error.

## Verify it is being read

```bash
# Is this runtime detected, and would this install unlock it?
clawmetry runtimes --json | jq '.runtimes[] | select(.id=="grok")'

# Why is it locked, if it is?
clawmetry runtimes --why grok

# Any sessions ingested yet?
curl -s 'http://localhost:8900/api/local/sessions?limit=5' \
  | jq '.rows[] | {session_id, agent_id, events, cost_usd}'
```

If detection succeeds but no sessions appear, work through [Troubleshooting](/docs/ops/troubleshooting/) — the usual causes are a relocated data directory (set the override above), a session limit that is hiding older runs, or a runtime that simply has not written anything yet.