@molecule/api-agent-transcript-claude-code

Claude Code transcript reader for @molecule/api-agent-transcript.

Reads both forms of a Claude Code session into a normalized AgentSession: the session log Claude Code keeps at ~/.claude/projects/<project>/<session-id>.jsonl (full fidelity: the assistant's markdown as written, per-message model and timestamps, and the complete text of every Write / Edit / MultiEdit), and the plain text /export writes (the terminal rendering: user ❯, assistant ●, tool calls such as Write(path) with the lines they wrote).

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-claude-code'

setProvider(provider)
const session = readTranscript({
  text: readFileSync('session.jsonl', 'utf8'),
  fileName: 'session.jsonl',
})
// session.turns: [{ role: 'user', text: '…as typed…' }, { role: 'assistant', model: 'claude-…', text, files }]

Type

provider

Installation

npm install @molecule/api-agent-transcript-claude-code @molecule/api-agent-transcript

API

Functions

looksLikeExportText(text)

Whether a text looks like a Claude Code /export.

function looksLikeExportText(text: string): boolean

• text — The file's text.

Returns: True when it carries the export's header or both of its speaker markers.

readExportText(text)

Read a Claude Code /export text.

function readExportText(text: string): AgentSession

• text — The export's text.

Returns: The normalized session.

looksLikeSessionJsonl(text)

Whether a text looks like a Claude Code session log.

function looksLikeSessionJsonl(text: string): boolean

• text — The file's text.

Returns: True when the first parseable lines are Claude Code log records.

readSessionJsonl(text)

Read a Claude Code session log.

function readSessionJsonl(text: string): AgentSession

• text — The .jsonl text.

Returns: The normalized session.

Constants

provider

Reads Claude Code sessions: the session log (.jsonl) and the /export text.

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-claude-code'

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

Injection Notes

Requirements

Peer dependencies:

• @molecule/api-agent-transcript ^1.0.0

Runtime Dependencies

• @molecule/api-agent-transcript

• Prefer the .jsonl when you have it. The /export text is a rendering: markdown is already applied (a ## heading arrives as heading, **bold** as bold), paragraphs are re-joined from terminal wrapping, and the model is only the display name in the header (Haiku 4.5). Edits the terminal showed collapsed ("Made 1 edit") carry no text, and a truncated preview (… +N lines) is marked complete: false.

• Dropped from user turns: slash-command echoes (<command-name> …), their output, <system-reminder> text, tool results, and lines Claude Code marks isMeta. A subagent's own messages (isSidechain) are not part of the session.

• Verified against Claude Code 2.1.281's own files; the older > / ⏺ markers are accepted too.