Grok CLI¶
Grok CLI combines a prompt-history audit log with full session transcript files. agentgrep searches user prompts by default. Targeted effort resolves a prompt record’s session UUID to the corresponding project transcript; full assistant, reasoning, and tool records also require conversation or all scope.
Base path: ~/.grok (env override: GROK_HOME).
observed_version: grok 1.0.0 (observed 2026-08-08).
Grok stores data under ~/.grok/sessions/ using URL-encoded project
paths as directory keys (e.g. %2Fhome%2Fd%2Fwork%2Fpython%2Fproj).
Each session is identified by a UUIDv7 (timestamp-sortable).
Stores¶
- Role:
prompt_history- Format:
jsonl- Coverage:
default_search- Adapter:
grok.prompt_history_jsonl.v1
- Role:
primary_chat- Format:
jsonl- Coverage:
default_search- Adapter:
grok.sessions_jsonl.v1
- Role:
supplementary_chat- Format:
sqlite- Coverage:
default_search- Adapter:
grok.session_search_sqlite.v1
- Role:
supplementary_chat- Format:
json_object- Coverage:
default_search- Adapter:
grok.subagents_json.v1
- Role:
app_state- Format:
jsonl- Coverage:
catalog_only- Adapter:
-
- Role:
app_state- Format:
json_object- Coverage:
catalog_only- Adapter:
-
- Role:
persistent_memory- Format:
md_frontmatter- Coverage:
inspectable- Adapter:
grok.memory_text.v1
- Role:
app_state- Format:
sqlite- Coverage:
catalog_only- Adapter:
-
- Role:
app_state- Format:
opaque- Coverage:
catalog_only- Adapter:
-
- Role:
plan- Format:
md_frontmatter- Coverage:
inspectable- Adapter:
grok.plans_text.v1
- Role:
app_state- Format:
text- Coverage:
catalog_only- Adapter:
-
- Role:
app_state- Format:
json_object- Coverage:
catalog_only- Adapter:
-
- Role:
app_state- Format:
jsonl- Coverage:
catalog_only- Adapter:
-
- Role:
app_state- Format:
jsonl- Coverage:
catalog_only- Adapter:
-
- Role:
app_state- Format:
text- Coverage:
catalog_only- Adapter:
-
- Role:
instruction- Format:
md_frontmatter- Coverage:
catalog_only- Adapter:
-
grok.prompt_history¶
JSONL per-project user-prompt audit log. Keys: timestamp (ISO-8601 nanosecond), session_id (UUIDv7), prompt (text), is_bash (bool).
- Agent:
Grok
- Role:
prompt_history- Format:
jsonl- Coverage:
default_search- Path:
${GROK_HOME or ${HOME}/.grok}/sessions/<url_encoded_project>/prompt_history.jsonl- Adapter:
grok.prompt_history_jsonl.v1- Data version:
-- Version strategies:
-- Observed:
grok 1.0.0 (2026-08-08)
- Default search:
yes
Record keys observed (1.0.0, 2026-08-08)
- Keys:
is_bash,prompt,session_id,timestamp
grok.sessions¶
JSONL full session transcripts. type discriminates system/user/assistant/reasoning/tool_result/backend_tool_call. Assistant tool calls live in a tool_calls array on the assistant record; backend_tool_call records host-side calls. reasoning records carry a readable summary array of {type: summary_text, text} blocks plus an opaque encrypted_content blob; agentgrep does not surface them because the adapter reads only content, which reasoning records omit. content is text or a content-blocks array. No record of any type carries a timestamp key, so the adapter backfills the source mtime. Agent-injected turns are written as user records tagged with synthetic_reason (system_reminder, project_instructions); the adapter does not yet read that key, so they are indexed as user prompts.
- Agent:
Grok
- Role:
primary_chat- Format:
jsonl- Coverage:
default_search- Path:
${GROK_HOME or ${HOME}/.grok}/sessions/<url_encoded_project>/<session_uuid>/chat_history.jsonl- Adapter:
grok.sessions_jsonl.v1- Data version:
-- Version strategies:
-- Observed:
grok 1.0.0 (2026-08-08)
- Default search:
yes
Record keys by type observed (1.0.0, 2026-08-08)
- assistant:
content,model_fingerprint,model_id,reasoning_effort,tool_calls,type- reasoning:
encrypted_content,id,status,summary,type- system:
content,type- tool_result:
content,tool_call_id,type- user:
content,prior_turn_interrupt,prompt_index,synthetic_reason,type
Full per-session transcript with tool calls; grok.prompt_history is the user-prompts-only audit log.
grok.session_search¶
SQLite with FTS5. Table session_docs: session_id, cwd, updated_at (unix seconds), title (generated), content (full-text index), content_hash, last_indexed_offset. A meta table carries session_search_schema_version (4) and last_bootstrap_at; PRAGMA user_version stays 0.
- Agent:
Grok
- Role:
supplementary_chat- Format:
sqlite- Coverage:
default_search- Path:
${GROK_HOME or ${HOME}/.grok}/sessions/session_search.sqlite- Adapter:
grok.session_search_sqlite.v1- Data version:
-- Version strategies:
-- Observed:
grok 1.0.0 (2026-08-08)
- Default search:
yes
SQLite tables observed (1.0.0, 2026-08-08)
- meta columns:
key,value- session_docs columns:
session_id,cwd,updated_at,title,content,content_hash,last_indexed_offset- session_docs_fts columns:
title,content- session_docs_fts_config columns:
k,v- session_docs_fts_data columns:
id,block- session_docs_fts_docsize columns:
id,sz- session_docs_fts_idx columns:
segid,term,pgno
Pre-indexed session titles and content for fast lookup. De-duplicate against grok.sessions by session_id.
grok.subagents¶
Per-subagent dispatch record. One JSON object per delegated subagent: prompt (the delegated instruction), description, subagent_type, tool_calls, turns, and parent/child session linkage. The subagent’s own turns are not persisted separately, so this prompt is the only searchable record of the delegation.
- Agent:
Grok
- Role:
supplementary_chat- Format:
json_object- Coverage:
default_search- Path:
${GROK_HOME or ${HOME}/.grok}/sessions/<url_encoded_project>/<session_uuid>/subagents/<subagent_uuid>/meta.json- Adapter:
grok.subagents_json.v1- Data version:
-- Version strategies:
-- Observed:
grok 1.0.0 (2026-08-08)
- Default search:
yes
Subagent dispatch prompts are conversation content with no sibling transcript; parity with claude.projects.subagent and cursor-cli.subagent_transcripts.
grok.sessions.events¶
Per-session event stream. type values include turn_started, turn_ended, loop_started, first_token, phase_changed, tool_started, tool_completed, permission_requested/resolved, and an mcp_* lifecycle family (illustrative, not exhaustive). A per-record schema_version (“1.0”) rides on turn_started.
- Agent:
Grok
- Role:
app_state- Format:
jsonl- Coverage:
catalog_only- Path:
${GROK_HOME or ${HOME}/.grok}/sessions/<url_encoded_project>/<session_uuid>/events.jsonl- Adapter:
-
- Data version:
-- Version strategies:
-- Observed:
grok 1.0.0 (2026-08-08)
- Default search:
no
grok.sessions.summary¶
Per-session summary: id, cwd, session_summary, created_at, updated_at, num_messages, current_model_id, git metadata, generated_title, agent_name.
- Agent:
Grok
- Role:
app_state- Format:
json_object- Coverage:
catalog_only- Path:
${GROK_HOME or ${HOME}/.grok}/sessions/<url_encoded_project>/<session_uuid>/summary.json- Adapter:
-
- Data version:
-- Version strategies:
-- Observed:
grok 1.0.0 (2026-08-08)
- Default search:
no
grok.memory¶
Persistent memory Markdown managed by Grok’s memory system. Covers the flat memory/MEMORY.md and the per-project memory/<project-slug>-<hash8>/MEMORY.md subtree. The companion index.sqlite is not separately enumerated; it is a chunk store (chunks) with both an FTS5 mirror (chunks_fts) and a sqlite-vec embedding index (chunks_vec), not an FTS index alone. Grok derives the directory name from the git remote URL, so every clone and worktree of one repository shares a memory directory. Inspectable opt-in.
- Agent:
Grok
- Role:
persistent_memory- Format:
md_frontmatter- Coverage:
inspectable- Path:
${GROK_HOME or ${HOME}/.grok}/memory/**/MEMORY.md- Adapter:
grok.memory_text.v1- Data version:
-- Version strategies:
-- Observed:
grok 1.0.0 (2026-08-08)
- Default search:
no
grok.logs¶
Structured application logs: ts, src, pid, lvl, msg, ctx. Debugging diagnostics, not chat content.
- Agent:
Grok
- Role:
app_state- Format:
jsonl- Coverage:
catalog_only- Path:
${GROK_HOME or ${HOME}/.grok}/logs/unified.jsonl- Adapter:
-
- Data version:
-- Version strategies:
-- Observed:
grok 1.0.0 (2026-08-08)
- Default search:
no
grok.worktrees_db¶
SQLite database tracking git worktrees created by Grok.
- Agent:
Grok
- Role:
app_state- Format:
sqlite- Coverage:
catalog_only- Path:
${GROK_HOME or ${HOME}/.grok}/worktrees.db- Adapter:
-
- Data version:
-- Version strategies:
-- Observed:
grok 1.0.0 (2026-08-08)
- Default search:
no
grok.config¶
grok.plans¶
Per-session plan-mode Markdown — the agent’s working plan for the session. Inspectable, parity with claude.plans and cursor-cli.plans; not searched by default.
- Agent:
Grok
- Role:
plan- Format:
md_frontmatter- Coverage:
inspectable- Path:
${GROK_HOME or ${HOME}/.grok}/sessions/<url_encoded_project>/<session_uuid>/plan.md- Adapter:
grok.plans_text.v1- Data version:
-- Version strategies:
-- Observed:
grok 1.0.0 (2026-08-08)
- Default search:
no
grok.sessions.system_prompt¶
The rendered system prompt for the session (agent instructions plus injected context). Agent-side boilerplate, largely shared across sessions; documented for inventory, not searched.
- Agent:
Grok
- Role:
app_state- Format:
text- Coverage:
catalog_only- Path:
${GROK_HOME or ${HOME}/.grok}/sessions/<url_encoded_project>/<session_uuid>/system_prompt.txt- Adapter:
-
- Data version:
-- Version strategies:
-- Observed:
grok 1.0.0 (2026-08-08)
- Default search:
no
grok.sessions.prompt_context¶
Session prompt-context metadata: working_directory, agents_md_files, persona_summaries, os_name, current_date, prompt_mode, audience, version. Configuration, not chat.
- Agent:
Grok
- Role:
app_state- Format:
json_object- Coverage:
catalog_only- Path:
${GROK_HOME or ${HOME}/.grok}/sessions/<url_encoded_project>/<session_uuid>/prompt_context.json- Adapter:
-
- Data version:
-- Version strategies:
-- Observed:
grok 1.0.0 (2026-08-08)
- Default search:
no
grok.sessions.hunk_records¶
Edit-attribution JSONL (filePath, hunkStart/End, linesAdded/Removed, authorType, promptIndex, eventType). Code-change telemetry, no prompt payload; documented, not searched.
- Agent:
Grok
- Role:
app_state- Format:
jsonl- Coverage:
catalog_only- Path:
${GROK_HOME or ${HOME}/.grok}/sessions/<url_encoded_project>/<session_uuid>/hunk_records.jsonl- Adapter:
-
- Data version:
-- Version strategies:
-- Observed:
grok 1.0.0 (2026-08-08)
- Default search:
no
grok.sessions.updates¶
ACP-style session/update notification stream (method, params.sessionId, update payloads). Protocol traffic, not chat; documented, not searched.
- Agent:
Grok
- Role:
app_state- Format:
jsonl- Coverage:
catalog_only- Path:
${GROK_HOME or ${HOME}/.grok}/sessions/<url_encoded_project>/<session_uuid>/updates.jsonl- Adapter:
-
- Data version:
-- Version strategies:
-- Observed:
grok 1.0.0 (2026-08-08)
- Default search:
no
grok.sessions.terminal¶
Per-tool-call terminal stdout/stderr logs (thousands per active project). Tool output, not chat, and high-volume; documented for inventory and deliberately not searched.
- Agent:
Grok
- Role:
app_state- Format:
text- Coverage:
catalog_only- Path:
${GROK_HOME or ${HOME}/.grok}/sessions/<url_encoded_project>/<session_uuid>/terminal/call-<id>.log- Adapter:
-
- Data version:
-- Version strategies:
-- Observed:
grok 1.0.0 (2026-08-08)
- Default search:
no
grok.skills¶
skills/<name>/SKILL.md skill-instruction files (currently the bundled set mirrored under bundled/skills/; users can author their own). Parity with claude.skills and cursor-cli.skills.
- Agent:
Grok
- Role:
instruction- Format:
md_frontmatter- Coverage:
catalog_only- Path:
${GROK_HOME or ${HOME}/.grok}/skills/<name>/SKILL.md- Adapter:
-
- Data version:
-- Version strategies:
-- Observed:
grok 1.0.0 (2026-07-03)
- Default search:
no
Record schemas¶
Prompt history¶
grok.prompt_history is a per-project user-prompt audit log. One
record per prompt, append-only.
{"timestamp": "2026-05-25T10:00:00.000000000Z",
"session_id": "019729a0-...", "prompt": "...", "is_bash": false}
Keys: timestamp (ISO-8601 nanosecond), session_id (UUIDv7),
prompt (user text), is_bash (bool — true for shell commands).
Session transcripts¶
grok.sessions contains full session transcripts. The type field
discriminates record kinds: system, user, assistant, reasoning,
tool_result, backend_tool_call.
Not every user record is something you typed. Grok writes its own
injected turns into the same stream, tagged with a synthetic_reason
key naming why — system_reminder for tool nudges, project_instructions
for AGENTS.md content. In the sample this page was verified against,
52 of 101 user records carried one. agentgrep does not yet read that
key, so those injected turns are searched as if you had typed them; a
prompt result you do not recognise is most likely one of these.
Assistant tool calls live in a tool_calls
array on the assistant record; reasoning records carry a readable summary
array of {type: summary_text, text} blocks plus an opaque encrypted_content
blob, but agentgrep does not surface them because the adapter reads only
content, which reasoning records omit. content is either a plain string or
a content-blocks array.
{"type": "user", "content": "explain the design"}
Transcript records carry no clock of their own — no record of any type
has a timestamp key — so agentgrep backfills the transcript file’s
modification time. That dates a record to its session rather than to
its turn, which is enough to order results and answer a date filter but
not to distinguish two turns in the same session. The per-prompt clock
lives next door, in the prompt-history log.
An assistant record names the model that answered in model_id — Grok’s
spelling of the key other agents call model — and agentgrep surfaces it as
the record’s model, so model:grok-* reaches Grok transcripts.
Subagent delegations¶
grok.subagents is one JSON dispatch object per delegated subagent
under sessions/<project>/<session>/subagents/<subagent>/meta.json. The
subagent’s own turns are not persisted separately, so the delegated prompt is
the only searchable record of the delegation.
{"subagent_id": "019e6626-...", "parent_session_id": "019e660d-...",
"subagent_type": "code-explorer", "description": "Map the auth module",
"prompt": "Explore the auth module and summarize ...", "tool_calls": []}
agentgrep emits the prompt as one supplementary-chat record titled
with description; subagent_type and parent_session_id are
attached as metadata.
Session search index¶
grok.session_search is a SQLite database with FTS5. Table
session_docs:
Column |
Type |
Description |
|---|---|---|
|
TEXT |
UUIDv7 primary key |
|
TEXT |
Working directory |
|
INTEGER |
Unix seconds |
|
TEXT |
Generated session title |
|
TEXT |
Full-text indexed body |
|
TEXT |
Content digest |
|
INTEGER |
Incremental-index cursor |
A sibling meta table holds session_search_schema_version (4) and
last_bootstrap_at; PRAGMA user_version stays 0. agentgrep converts
updated_at to ISO-8601 for timestamp consistency with other adapters.
Plans¶
grok.plans is per-session plan-mode Markdown at
sessions/<project>/<session>/plan.md — the agent’s working plan. Inspectable
(opt-in), parity with claude.plans and
cursor-cli.plans; not searched by default.
Project context¶
Store |
|
|
|
|---|---|---|---|
assistant record’s |
|
— |
|
— |
|
— |
|
— |
|
— |
%2F is a lossless escape, so the project directory key inverts exactly
— the lossless tier. agentgrep decodes it back
into the working directory and reports it on every prompt-history and
transcript record, which is the same absolute path
grok.session_search already stored literally in
session_docs.cwd. All three stores therefore answer --cwd and cwd:
with one working directory per session.
That encoding has one exception, and it is the reason a deeply nested
project can behave differently from a shallow one. When the encoded
name would exceed 255 bytes, Grok names the directory with a slug plus
a hash instead and writes the real path into a .cwd file inside the
group. A slug does not invert, so agentgrep reads the sidecar; without
it those sessions would lose cwd while every shallower project kept
it. A directory that neither decodes nor carries a .cwd file yields
no cwd rather than a plausible one.
branch: does not reach this backend, but not because Grok is unaware
of git. Each session’s summary.json carries head_branch,
head_commit, git_root_dir, and git_remotes — no store row reads
that file, so the branch is on disk and out of reach rather than
absent.