claudetranscript

package
v0.1.0-rc.2 Latest Latest
Warning

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

Go to latest
Published: Nov 3, 2026 License: MIT Imports: 12 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 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 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