# Grok Build

> Import Grok Build sessions with their tool calls, token usage, cost, and forks.

Hansard reads each Grok Build session's update stream as the order of events,
and adds details from matching usage and chat files.

## Source IDs

| Source       | Use it for                                                                                        |
| ------------ | ------------------------------------------------------------------------------------------------- |
| `grok-build` | Grok Build sessions in `~/.grok/sessions`: session updates, prompt usage records, and chat files. |

## How the import works

Hansard treats each session's saved update stream, `updates.jsonl`, as the true
order of events. It replays those updates to build user and assistant messages,
tool calls and results, edits, status changes, and other session events. A chat
file can add detail to those events, but it can never reorder or replace
events that Grok Build recorded in the update stream.

Matching prompt usage records and chat files add tool arguments, model names,
tokens, cost, and project details. Hansard adds them only when the session ID
matches. A forked session stays its own conversation and records which session
it came from. High-volume timing updates are summarized instead of appearing
as messages. Importing again updates existing conversations by session ID.

Encoded project folders include nested `/tmp` and `/private/tmp` working
directories. Temporary projects use the usual `path:` repository identity
when no Git repository is recorded. Grok's external usage lock slots are not
history sources. Session lock files do not enter the archive.

## Import and keep current

**Import now**

```sh
hansard import --source grok-build --since all
hansard index rebuild
```

**Keep current**

With **Automatic** source selection, the watcher already includes
`grok-build`. With a **Custom** list, enable it. The watcher picks it up within 30 seconds:

```sh
hansard config sources enable grok-build
```

## Review the import in the app

1. When the import finishes, open **Conversations** and select **Filter & sort**.
2. Set **Source** to **Grok Build** and set **Time** to the window you imported. Use **Folder** to narrow the list when you use this harness in several projects.
3. Select a conversation to check its messages, tool calls, files, commits, model, and token usage.

To keep archiving new sessions from a local harness, open **Settings → Imports**. **Automatic** follows every supported harness installed on this computer. **Custom** lets you turn individual harnesses on or off. Cloud sources and account exports never run from here; each needs its own import command. If a conversation you expect is missing after you reset the filters, run the import command on this page again with `--explain-skips` where the source supports it.

## What Hansard preserves

- Turn order, user and assistant messages, tool calls, plan and mode changes,
  hooks, subagent activity, permission changes, and MCP server events.
- Provider request failures, retry state, turn results, and recorded elapsed
  turn time. A failed request does not imply token usage.
- Complete prompt usage records with input and output tokens, cache reads,
  reasoning tokens, model calls, API duration, and the cost Grok Build
  reported.
- Matching chat details such as tool arguments, model, reasoning effort, and
  which messages you sent while the agent was working.
- For a fork, the parent session and fork time. Forks are not counted as
  subagents.
- Recorded workspace, Git root, branch, commit, format version, and provider
  message counters, including zero. Provider counters remain separate from
  the number of normalized messages.
- Repository candidates from recorded Git remotes. One unambiguous
  repository takes precedence over a changed or missing checkout; an explicit
  `.hansard.yaml` override takes precedence over the recorded remotes.

## Known limitations

- Hansard requires a stable session snapshot. Incomplete JSON, concurrent
  writes, and unsupported chat format versions leave the previous archive
  intact for retry. A changed or shortened archived update prefix cannot
  replace existing history.
- Snapshot limits are 64 MiB per file, 128 MiB per session, 4,096 files, and
  eight nested directory levels. Capacity failures report the affected source.
- Session directories without `updates.jsonl` are not imported.
- High-volume phase and timing updates are summarized, not shown as messages.
- Grok Build's shared prompt history for each working directory is not
  attached to individual conversations.
- Peak `_meta.totalTokens` shows how full the context was, not billed usage.
- The current model setting is preserved separately from recorded model usage.
  A setting alone cannot identify the model used for an earlier reply.
- Conflicting or unrecognized recorded Git remotes cannot choose a repository.
  The importer falls back to the working directory's normal repository lookup.
- A tool preview does not produce a result until Grok Build saves the tool's
  final update.
- Unknown update types produce a warning and retain their type counts and raw
  records. A conversation with only unknown updates has no decoded messages;
  its raw backup is preserved for a later importer update.
- An unknown-only capture cannot replace an earlier decoded conversation. That
  update is skipped with a warning; the current provider source must remain
  available for a later importer update.

## Refresh an existing archive

Reimport to refresh model attribution, provider failure messages, elapsed turn
times, recorded metadata, and repository identity:

```sh
hansard import --source grok-build --since all
hansard index rebuild
```