Grok Build session format

Store and files

Grok Build stores sessions below ${GROK_HOME:-~/.grok}/sessions/<encoded-cwd>/<session-id>/. DEJA_GROK_ROOT overrides where deja reads sessions; GROK_HOME relocates the whole Grok tree, including config.toml. updates.jsonl is the conversation stream and sibling summary.json carries metadata. A .cwd file beside session directories can recover the working directory when summary metadata is absent. grok-dev, another CLI sharing ~/.grok, writes no session files: its history is in ${GROK_HOME:-~/.grok}/grok.db, a SQLite store read through sqlite3, and DEJA_GROK_DB points deja at another copy. Each row of messages is an AI SDK message: text parts are the turn, tool-call parts become commands (bash), files, edits and written lines (read_file, write_file, edit_file under path), and the tool-result parts on tool rows tool output.

The working-directory group is URL-encoded, although observed names are not always encoded consistently. deja prefers summary.json and .cwd over decoding the directory name.

Three products share this directory

Grok Build reads config.toml. grok-dev keeps its history in grok.db and

reads MCP servers from ~/.grok/user-settings.json, as an array under

mcp.servers of {id, label, enabled, transport, command, args} rather than a

map. deja install grok writes both files. @vibe-kit/grok-cli (npm) reads

MCP servers only from the project's .grok/settings.json and has no user-level

MCP, so a global deja install cannot wire it: run `grok mcp add deja

--command deja --args mcp` inside a project to use deja there. What reaches it

from install is ~/.grok/GROK.md, which it reads only when the project has no

.grok/GROK.md of its own.

Records

summary.json includes info.id, info.cwd, titles, and RFC 3339 creation/update times. Conversation lines use ACP session updates:

{"timestamp":1784278802,"params":{"update":{"sessionUpdate":"agent_message_chunk","content":{"type":"text","text":"The first chunk "}},"_meta":{"promptId":"prompt-1"}}}

user_message_chunk maps to user and agent_message_chunk maps to assistant. Content is usually { "type": "text", "text": "..." }; arrays of text-bearing parts are also accepted. Timestamps accept Unix seconds or milliseconds. _meta.agentTimestampMs is the fallback.

Consecutive assistant chunks with the same promptId are joined. Consecutive user chunks with the same promptIndex are joined.

Spawn tree

summary.json records what a session is and where it came from:

session_kind (subagent, subagent_fork), parent_session_id, agent_name

and forked_at. deja reads the first three into the session record — they show

up in --json as kind, parent and agent, and deja show names the

session a child was spawned from and the children a parent spawned. A

subagent names no parent_session_id on 1.0.41; its parent's

updates.jsonl holds a subagent_spawned record naming both ends, and deja

reads the edge from that record (#5264). A --fork-session copy names its

source and forked_at and is read as a fork of it, so neither one comes back

to the other as prior work (#5263). A

grok -p run is marked headless, which says how the session was started,

not that something spawned it, so deja records no kind for it (#4585).

A fork's copy starts with every record of its source, rewritten

under the fork's sessionId and outer timestamp; _meta.eventId still

names the source. deja keeps a fork's own records and leaves the copies to the source,

so search finds the source's turns once and blame names the session that

wrote a line, not a fork made after it (#5235). A resumed or forked session

already holds the start digest in chat_history.jsonl, which Grok sends back

to the model, so deja does not send another (#5262).

Status line

deja install grok-auto adds [ui.status_line] with type = "command" to the

user config.toml; Grok ignores the table in a project config. It pipes

Claude's payload, transcript_path included once the first prompt is in, and

reads the config at startup only. A status line already set there is left

alone. Rendered live on 1.0.41.

Known quirks and drift

  • The ACP stream contains large tool updates. deja filters lines for message chunk kinds before decoding JSON.
  • Rewind can truncate and regrow updates.jsonl, which looks like growth from

the outside. deja compares the prefix hash it recorded: an intact prefix takes

the append path and reads only the new bytes, a moved one reparses the stream

in full. A live session used to rewrite the whole index on every touch.

  • generated_title takes precedence over session_summary.
  • Missing summary files fall back to directory IDs and the .cwd or URL-decoded path.
  • Path encoding is ambiguous when upstream leaves separators or percent escapes in different forms.
  • deja resume prints grok --resume <id> and runs it in the recovered

working directory, since Grok Build scopes its session list by directory.

It reopens a session from any directory, so a deleted one gets no cd and

a note instead (#4459).

Rows that came out of grok.db belong to the other product and get an error

instead.

  • Grok Build reads deja's wiring three ways at once: [mcp_servers.deja] in

config.toml, ~/.grok/hooks/deja.json in Claude Code's hook shape, and the

shared skill in ~/.agents/skills. It also scans ~/.claude.json and

~/.cursor/mcp.json, so a machine wired for those has deja in Grok already.

~/.grok/GROK.md is the exception: that file is for the other product, and

Grok Build's home rules are Agents.md, AGENTS.md, Claude.md, CLAUDE.md.

  • The hooks run, but on 1.0.5 what session start, the prompt and both tool

events print is discarded — measured against a stubbed proxy by reading the

request the model was sent. The one reply Grok applies is a PreToolUse

updatedInput, which is how memory reaches a spawned agent's prompt; the

rest of the wiring is there for its side effects, warming the index and

forgetting what a compaction threw away.

  • PostToolUse on Bash (grok maps it to run_terminal_command) runs

deja hook-tool-after. Grok 1.0.41's own hook docs say it fires for a

command that exited non-zero and hands additionalContext to the model with

the result. The output is read from toolResult.output_for_prompt; output

there is the raw bytes as a number array (#4499).

  • PreToolUse runs deja hook-tool on Bash, the file tools and the spawn

tools. On 1.0.41 its additionalContext reaches the model as a reminder

after the tool's result, so the line deja keeps for a file arrives at the

read before an edit as well as at the edit.

  • On 1.0.41 session start and the prompt are still passive: grok shows a

hook's systemMessage and drops its additionalContext, and the session's

chat_history.jsonl carries no deja-recall from either. Under grok, which

sets GROK_HOOK_EVENT on every hook it runs, hook-context and

hook-prompt hold their answer for the session's next PreToolUse or

PostToolUse, whose additionalContext does reach the model, and hand it

over there once; the session-start receipt still shows at once.

  • SessionEnd runs deja hook-session-end, so the session is back in the

next one's MCP recall.

Last verified: 2026-08-24 against Grok Build 1.0.5 (macos-aarch64)


deja reads this format and 51 others, and turns what it finds into memory your agents can search. See the harness matrix for what is wired where, or install it and search your own history.

Found this useful? Star deja-vu on GitHub.