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-cli v0.2.59 (observed 2026-06-21).
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-cli v0.2.59 (observed 2026-06-21) (2026-06-21)
- Default search:
yes
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.
- 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-cli v0.2.59 (observed 2026-06-21) (2026-06-21)
- Default search:
yes
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 (3) 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-cli v0.2.59 (observed 2026-06-21) (2026-06-21)
- Default search:
yes
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-cli v0.2.59 (observed 2026-06-21) (2026-06-21)
- 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-cli v0.2.59 (observed 2026-06-21) (2026-06-21)
- 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-cli v0.2.59 (observed 2026-06-21) (2026-06-21)
- 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_hash>/MEMORY.md subtree; the companion index.sqlite FTS index of the same content is not separately enumerated. 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-cli v0.2.59 (observed 2026-06-21) (2026-06-21)
- 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-cli v0.2.59 (observed 2026-06-21) (2026-06-21)
- 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-cli v0.2.59 (observed 2026-06-21) (2026-06-21)
- 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-cli v0.2.59 (observed 2026-06-21) (2026-06-21)
- 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-cli v0.2.59 (observed 2026-06-21) (2026-06-21)
- 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-cli v0.2.59 (observed 2026-06-21) (2026-06-21)
- 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-cli v0.2.59 (observed 2026-06-21) (2026-06-21)
- 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-cli v0.2.59 (observed 2026-06-21) (2026-06-21)
- 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-cli v0.2.59 (observed 2026-06-21) (2026-06-21)
- 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-cli v0.2.82 (observed 2026-07-03) (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. 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",
"timestamp": "2026-05-25T10:00:01.000000000Z"}
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 (3) 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, and a directory name that does
not decode to something path-shaped yields no cwd rather than a
plausible one.
Grok records no git branch, so branch: does not reach this backend.