claudetranscript

package
v0.2.0-rc.2 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 12, 2026 License: MIT Imports: 14 Imported by: 0

Documentation

Overview

Package claudetranscript reads Claude Code transcripts as typed, classified lines.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type AgentMeta

type AgentMeta struct {
	AgentType     string `json:"agentType"`
	Description   string `json:"description"`
	ToolUseID     string `json:"toolUseId"`
	SpawnDepth    int    `json:"spawnDepth"`
	ParentAgentID string `json:"parentAgentId"`
	Model         string `json:"model"`
}

AgentMeta is `subagents/agent-<A>.meta.json`, the primary spawn link. ToolUseID names the spawning call directly.

type Attachment

type Attachment struct {
	Type        string
	Prompt      string
	CommandMode string
	Origin      json.RawMessage
	Timestamp   *time.Time
}

Attachment is the typed envelope payload used by queued_command.

type Block

type Block struct {
	Type string
	Text string

	// tool_use
	ID    string
	Name  string
	Input json.RawMessage

	// tool_result
	ToolUseID string
	IsError   *bool
	Content   json.RawMessage

	Raw json.RawMessage
}

Block is one element of a message's content array.

func (Block) ResultText

func (b Block) ResultText() string

ResultText is a tool result block's text.

type Class

type Class string

Class is the line class.

const (
	ClassUser           Class = "user"
	ClassAssistant      Class = "assistant"
	ClassSystem         Class = "system"
	ClassAttachment     Class = "attachment"
	ClassProgress       Class = "progress"
	ClassControl        Class = "control"
	ClassUnknownControl Class = "unknown_control"
)

type Control

type Control struct {
	Mode            string
	PermissionMode  string
	AITitle         string
	AgentName       string
	LeafUUID        string
	LastPrompt      string
	BridgeSessionID string
	LastSequenceNum *int64
	Operation       string
	Content         string
	Value           json.RawMessage
}

Control is the union of the control-line payloads.

type File

type File struct {
	Path      string
	SessionID string
	AgentID   string
	Meta      *AgentMeta
	Lines     []Line
	// TornFinalLine is true when the last line was a partial write, which happens
	// while a session is still running.
	TornFinalLine bool
}

File is one transcript: the main thread, or one subagent.

func DecodeSubagent

func DecodeSubagent(r io.Reader, label, agentID string) (*File, error)

DecodeSubagent reads one subagent transcript that arrived outside a session directory, under the same checks as one listed beside its parent. The caller supplies the spawn link with Meta and adds the file with AddSubagent.

func (*File) Main

func (f *File) Main() bool

Main reports whether this is the main thread rather than a subagent.

type FileSources

type FileSources = traceprocessing.FileSources

type Line

type Line struct {
	Ordinal  int
	Class    Class
	Type     string
	UserKind UserKind
	Raw      json.RawMessage

	UUID       string
	ParentUUID string
	SessionID  string
	AgentID    string
	PromptID   string
	RequestID  string
	Timestamp  *time.Time

	IsSidechain bool
	IsMeta      bool
	CWD         string
	GitBranch   string
	Version     string

	// Subtype is the `system` line's subtype.
	Subtype string

	// PromptSource, Origin and ToolDenialKind appear on `user` lines. The first
	// two say whether a person typed the text or the harness injected it; the
	// third says why a tool was refused.
	PromptSource   string
	Origin         json.RawMessage
	ToolDenialKind string

	// ToolUseResult is the structured payload beside a tool result.
	ToolUseResult json.RawMessage

	// Message is the model message on `user` and `assistant` lines.
	Message *Message

	// Control carries the payload of a control line.
	Control Control
	// Attachment carries the small typed subset of attachment payloads.
	Attachment Attachment
}

Line is one JSONL record, classified and decoded as far as the model defines.

func Decode

func Decode(r io.Reader) (lines []Line, torn bool, err error)

Decode reads a transcript as classified lines.

func (*Line) Envelope

func (l *Line) Envelope() bool

Envelope reports whether this line takes part in the uuid chain.

type Message

type Message struct {
	ID         string
	Role       string
	Model      string
	StopReason *string
	Usage      *Usage
	Content    json.RawMessage
}

Message is one model message.

func (*Message) Blocks

func (m *Message) Blocks() []Block

Blocks decodes the content array. A string payload has no blocks.

func (*Message) Text

func (m *Message) Text() string

Text is the message's text.

type PatchHunk

type PatchHunk struct {
	OldStart int      `json:"oldStart"`
	OldLines int      `json:"oldLines"`
	NewStart int      `json:"newStart"`
	NewLines int      `json:"newLines"`
	Lines    []string `json:"lines"`
}

type ReadTranscript added in v0.2.0

type ReadTranscript func(path, name, agentID string) (*File, error)

ReadTranscript reads the local transcript at path, called name, as the subagent agentID or the main thread when agentID is empty. Reading.File returns what it must.

type Reading added in v0.2.0

type Reading struct {
	// contains filtered or unexported fields
}

Reading is one transcript decoded up to a byte offset, kept so that a transcript that grew is read from where the last read stopped rather than from its start. Continue decodes what was appended; File returns the transcript as a whole read of the same bytes would. The id checks Decode makes run over the whole transcript, earlier reads included.

A Reading leaves out Line.Raw, which only Survey reads, so the lines it keeps take about half the memory. A Reading is not safe for concurrent use.

func NewReading added in v0.2.0

func NewReading(name, label, agentID string) *Reading

NewReading starts reading the transcript called name (its base name, which can carry the session id), reported as label, of the subagent agentID or of the main thread when agentID is empty.

func (*Reading) Bytes added in v0.2.0

func (r *Reading) Bytes() int64

Bytes estimates the memory the lines read so far take.

func (*Reading) Continue added in v0.2.0

func (r *Reading) Continue(src io.Reader) (consumed int64, rest []byte, err error)

Continue decodes the lines r holds that end in a newline. r continues the transcript where the previous call's consumed bytes ended. A final line without a newline is not consumed: it is returned as rest, for File, and the next call reads it again from its first byte. After an error the Reading must be dropped.

func (*Reading) File added in v0.2.0

func (r *Reading) File(rest []byte) (*File, error)

File is the transcript read so far, followed by rest, the final line the last Continue left unread, decoded as Decode decodes a final line. The Reading is unchanged, and the File shares its lines, so neither may be changed. A final line that decodes is added to a copy of the lines: the spare capacity after them is where the next Continue appends, while the File may still be mapped. Claude Code ends every line it writes with a newline, so rest is normally empty or torn and nothing is copied.

func (*Reading) Lines added in v0.2.0

func (r *Reading) Lines() int

Lines is the number of lines read so far.

func (*Reading) Sum added in v0.2.0

func (r *Reading) Sum() uint32

Sum is the CRC-32C (traceprocessing.Castagnoli) of the bytes the lines read so far were decoded from: every byte Continue consumed.

type ResultEvidence

type ResultEvidence struct {
	Present         bool
	Text            string
	Stdout          string
	Stderr          string
	Interrupted     bool
	ExitCode        *int
	FilePath        string
	StructuredPatch []PatchHunk
	StartLine       *int
	NumLines        *int
	// AgentID names the subagent a spawn created. ResumedAgentID names the one a
	// SendMessage call woke up again.
	AgentID        string
	ResumedAgentID string
	Status         string
	Raw            json.RawMessage
}

ResultEvidence is what a tool-result line's `toolUseResult` says about the tool that ran.

func DecodeResultEvidence

func DecodeResultEvidence(raw json.RawMessage) ResultEvidence

type Shape

type Shape struct {
	Versions   traceprocessing.Versions `json:"versions"`
	Content    map[string]int           `json:"content_shapes,omitempty"`
	UnreadKeys map[string]int           `json:"unread_keys,omitempty"`
}

func Survey

func Survey(files []*File) Shape

type Tree

type Tree struct {
	Main      *File
	Subagents []*File
	// contains filtered or unexported fields
}

func DecodeFiles

func DecodeFiles[T FileSources](fsys fs.FS, files T) (*Tree, error)

DecodeFiles decodes the explicitly listed session tree.

func DecodeLocalFiles

func DecodeLocalFiles[T FileSources](files T) (*Tree, error)

DecodeLocalFiles decodes an explicitly listed set of local files.

func DecodeLocalFilesWith added in v0.2.0

func DecodeLocalFilesWith[T FileSources](files T, read ReadTranscript) (*Tree, error)

DecodeLocalFilesWith is DecodeLocalFiles with each transcript read by read, which can continue an earlier Reading of it. Sidecars are read as DecodeLocalFiles reads them.

func SingleFileTree

func SingleFileTree(file *File) (*Tree, error)

SingleFileTree constructs the tree represented by one already-decoded main transcript.

func (*Tree) AddSubagent

func (t *Tree) AddSubagent(file *File) error

AddSubagent records a decoded subagent on the tree, checking it against its parent exactly as a listed one is.

func (*Tree) Files

func (t *Tree) Files() []*File

Files is every transcript in the tree, main first.

func (*Tree) SubagentForToolUse

func (t *Tree) SubagentForToolUse(toolUseID string) *File

SubagentForToolUse returns the transcript a tool call spawned, or nil.

type Usage

type Usage struct {
	InputTokens              int64
	OutputTokens             int64
	CacheCreationInputTokens int64
	CacheReadInputTokens     int64

	// CacheWrite1h is usage.cache_creation.ephemeral_1h_input_tokens. Nil means
	// the transcript did not report it (no cache_creation object, or a value
	// that is not an integer).
	CacheWrite1h *int64
	// Speed is usage.speed verbatim ("standard", "fast"); empty when absent.
	Speed string
}

Usage is the token accounting of one reply: four disjoint buckets, plus the cache-write TTL split and the service speed when the transcript reports them.

type UserKind

type UserKind string

UserKind discriminates what a `user` line carries.

const (
	UserText        UserKind = "user_text"
	UserToolResults UserKind = "user_tool_results"
	UserMixed       UserKind = "user_mixed"
	UserOther       UserKind = "user_other"
)

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL