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_titletakes precedence oversession_summary.- Missing summary files fall back to directory IDs and the
.cwdor URL-decoded path. - Path encoding is ambiguous when upstream leaves separators or percent escapes in different forms.
deja resumeprintsgrok --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.
PostToolUseonBash(grok maps it torun_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).
PreToolUserunsdeja hook-toolonBash, 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.
SessionEndrunsdeja 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.