Grok Build

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

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:

hansard config sources enable grok-build

Review the import in the app

1. When the import finishes, open Sessions and selectFilter & sort.
2. Set Source to Grok Build and setTime to the window you imported. UseFolder 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, openSettings → Imports. Automaticfollows every supported harness installed on this computer.Custom lets you turn individual harnesses on or off. Cloud sources turn on separately under Cloud agents, and ChatGPT, Claude.ai, Gemini, and Gemini Notebook / NotebookLM exports import withImport export…. Each also has 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:

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