@molecule/api-agent-transcript-gemini-cli

Gemini CLI transcript reader for @molecule/api-agent-transcript.

Reads Gemini CLI's saved sessions into a normalized AgentSession: the session log it writes as you work (~/.gemini/tmp/<project>/chats/session-*.jsonl), the older one-object session file (session-*.json), and the checkpoint /chat save <tag> writes (checkpoint-<tag>.json).

Auto-generated, AI-first package reference for the molecule.dev ecosystem. It is written to be read by coding agents as much as by people, and is generated from this package's source — edit src/index.ts JSDoc, not this file.

Quick Start

import { readFileSync } from 'node:fs'
import { readTranscript, setProvider } from '@molecule/api-agent-transcript'
import { provider } from '@molecule/api-agent-transcript-gemini-cli'

setProvider(provider)
const file = 'session-2026-09-29T10-00-a1b2c3d4.jsonl'
const session = readTranscript({ text: readFileSync(file, 'utf8'), fileName: file })
console.log(session.model, session.turns.length)

Type

provider

Installation

npm install @molecule/api-agent-transcript-gemini-cli @molecule/api-agent-transcript

API

Functions

`partText(content)`

The text of a Gemini PartListUnion (a string, one part, or an array of them). Thought parts are left out.

function partText(content: unknown): string

content — The content.

Returns: The text.

`looksLikeGeminiSession(text)`

Whether a text is one of Gemini CLI's session shapes.

function looksLikeGeminiSession(text: string): boolean

text — The file's text.

Returns: True only on a positive match.

`readGeminiSession(text)`

Read a Gemini CLI session in any of its three shapes.

function readGeminiSession(text: string): AgentSession

text — The file's text.

Returns: The normalized session.

Constants

`provider`

Reads Gemini CLI sessions: the session log, the older session file and /chat save checkpoints.

const provider: AgentTranscriptReader

Core Interface

Implements @molecule/api-agent-transcript interface.

Bond Wiring

Setup function to register this provider with the core interface:

import { setProvider } from '@molecule/api-agent-transcript'
import { provider } from '@molecule/api-agent-transcript-gemini-cli'

export function setupAgentTranscriptGeminiCli(): void {
  setProvider(provider)
}

Injection Notes

Requirements

Peer dependencies:

@molecule/api-agent-transcript ^1.0.0

Runtime Dependencies

@molecule/api-agent-transcript
The session log and session file name the model on every reply (model) and time every message; a /chat save checkpoint names neither.
The log is replayed the way Gemini CLI reloads it: a $set.messages checkpoint replaces what came before, and $rewindTo drops the named message and everything after it — so a rewound branch is not in the result.
Left out of user turns: slash commands (/…), help queries (?…) and injected context (<session_context>, <hook_context>), plus the model's reply to injected context in a checkpoint. info, error and warning records are the CLI's own notices and are left out too.
A user message shows as typed (displayContent) when the log keeps it, not the version with @file contents expanded.
Files: successful write_file calls are whole files; successful replace calls contribute their new_string.
Format verified 2026-09-29 against the gemini-cli source (packages/core/src/services/chatRecordingTypes.ts).

`@molecule/api-agent-transcript-gemini-cli`

How it works

Reference