Gemini CLI Chat Record Parsing#

JSONL File Structure#

Gemini CLI writes session history as a JSONL event log in ~/.gemini/tmp/. Each file is replayed in order to reconstruct conversation state. The record types are 1:

• Line 0 — metadata header: { sessionId, projectHash, startTime, lastUpdated, kind }. The kind field is "main" for a primary session or "subagent" for a delegated session. Subagent sessions also carry a parentSessionId link 2.
• Message records: { id, timestamp, type, content, tokens?, model?, toolCalls?, thoughts? } where type is "user", "gemini", "info", etc.
• $set checkpoints: Merge metadata into the session; if $set.messages is present it replaces all messages (the first user message of a session usually lives only here, written by updateMessagesFromHistory()).
• $rewindTo records: Remove the named message and all subsequent ones.

The main parser entry point is parseGeminiSession() in src/sources/gemini.ts, which delegates replay to replay().

Duplicate-Message-ID Replay (Map.set In-Place Replacement)#

Gemini re-appends a turn with the same id whenever usage tokens or tool calls arrive after its initial text record (recordMessageTokens() / recordToolCalls() in the CLI). This means a turn can appear 2–3 times in the file 3.

The replay loop uses a Map<string, ReplayedRecord> and calls Map.set on every encountered id 4. Because Map preserves insertion order and set on an existing key updates the value without changing position, the final iteration order matches the original turn sequence 5.

ThoughtSummary Shape#

Thoughts parsed from a "gemini" message are { subject, description, timestamp } objects — not { text } 6. thoughtText() joins trimmed subject and description with "\n\n" and falls back to a plain text field if both are absent. Each thought becomes a "thinking" block in Decant's normalized output.

Token Field Semantics and Cost Normalization#

Gemini reports token counts in a non-standard layout. usageFrom() in src/sources/gemini.ts normalizes them:

This normalization satisfies three constraints simultaneously: accurate cost (cache reads priced differently), accurate context-window occupancy (input = true prompt tokens), and the reasoning-within-output contract required by Decant's downstream cost math 7.

$rewindTo Behavior#

rewind() in src/sources/gemini.ts implements two cases:

• Target not found → the entire Map is cleared (messages.clear()), matching Gemini CLI's own loader behavior 8.
• Target found → the target message and all messages inserted after it are deleted by iterating Map.keys() in order 9.

Built-in Tool Name Mapping#

Gemini CLI's built-in tools use snake_case names. They are mapped across three files:

src/buckets.ts — Activity Buckets#

toolBucket() assigns each tool to an activity category:

src/distill.ts — Command Decoding#

decodeCommand() extracts the shell command string from a tool call input. For run_shell_command it reads the "command" key 13; for exec_command / shell / local_shell it reads "cmd" 14. File tools (write_file, replace) are not handled here — they go through fileOp() separately.

src/enrich.ts — File References#

The GEMINI_FILE_TOOLS table 15 maps file tool names to their input parameter key and operation type:

These are used by keyedRef() to extract file path references from Gemini tool call inputs when session.toolType === "gemini" 16.