Molecule.dev

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

Provider bond · agent-transcript · API (Node) · v1.0.0 · Apache-2.0

Reads Claude Code sessions — the /export text and the session .jsonl — into a normalized agent session

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

npm · Source on GitHub · Implements @molecule/api-agent-transcript

How it works

@molecule/api-agent-transcript-claude-code is a provider bond on the API (Node) side: it implements the agent-transcript core interface (@molecule/api-agent-transcript) with a concrete vendor or library behind it.

Your code calls the core; you wire this provider once at startup. Swapping vendors later is one line in that wiring, not a rewrite.

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 }]

Works with: @molecule/api-agent-transcript

Reference

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).

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.

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.

readExportText(text)

Read a Claude Code /export text.

function readExportText(text: string): AgentSession
  • text — The export's text.

Returns: The normalized session.

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.