jsonl

Documentation

Index

• func WriteLines(path string, lines [][]byte) error
• type ContentBlock
  • func ParseContentBlocks(raw json.RawMessage) ([]ContentBlock, error)
• type Entry
  • func Parse(path string) ([]Entry, error)
  • func ParseRaw(path string) ([]Entry, [][]byte, error)
  • func (e *Entry) ContentPreview(maxLen int) string
  • func (e *Entry) HasImages() bool
  • func (e *Entry) IsConversational() bool
  • func (e *Entry) ToolUseIDs() []string
• type ImageSource
• type LightStats
  • func ScanLight(path string) (*LightStats, error)
• type Message
• type MessageType
• type Usage
  • func (u *Usage) TotalContextTokens() int

Functions

func WriteLines

func WriteLines(path string, lines [][]byte) error

WriteLines writes raw JSONL lines to a file atomically. It writes to a temp file first, then renames to the target path.

Types

type ContentBlock

type ContentBlock struct {
	Type      string          `json:"type"`
	Text      string          `json:"text,omitempty"`
	Name      string          `json:"name,omitempty"`
	ID        string          `json:"id,omitempty"`
	Input     json.RawMessage `json:"input,omitempty"`
	ToolUseID string          `json:"tool_use_id,omitempty"`
	Content   json.RawMessage `json:"content,omitempty"`
	IsError   bool            `json:"is_error,omitempty"`
	Source    *ImageSource    `json:"source,omitempty"`
	Caller    json.RawMessage `json:"caller,omitempty"`
}

ContentBlock represents a single block within a message content array.

func ParseContentBlocks

func ParseContentBlocks(raw json.RawMessage) ([]ContentBlock, error)

ParseContentBlocks parses message content into individual blocks. Content can be a JSON string (returns one text block) or an array of blocks.

type Entry

type Entry struct {
	Type             MessageType     `json:"type"`
	UUID             string          `json:"uuid,omitempty"`
	ParentUUID       string          `json:"parentUuid,omitempty"`
	Timestamp        time.Time       `json:"timestamp"`
	SessionID        string          `json:"sessionId,omitempty"`
	CWD              string          `json:"cwd,omitempty"`
	Version          string          `json:"version,omitempty"`
	GitBranch        string          `json:"gitBranch,omitempty"`
	IsSidechain      bool            `json:"isSidechain,omitempty"`
	UserType         string          `json:"userType,omitempty"`
	Slug             string          `json:"slug,omitempty"`
	PermissionMode   string          `json:"permissionMode,omitempty"`
	RequestID        string          `json:"requestId,omitempty"`
	Message          *Message        `json:"message,omitempty"`
	Data             json.RawMessage `json:"data,omitempty"`
	ToolUseID        string          `json:"toolUseID,omitempty"`
	ParentToolUseID  string          `json:"parentToolUseID,omitempty"`
	MessageID        string          `json:"messageId,omitempty"`
	Snapshot         json.RawMessage `json:"snapshot,omitempty"`
	ToolUseResult    json.RawMessage `json:"toolUseResult,omitempty"`
	IsSnapshotUpdate bool            `json:"isSnapshotUpdate,omitempty"`

	// Computed fields (not serialized to JSON)
	LineNumber int `json:"-"`
	RawSize    int `json:"-"`
}

Entry is the top-level structure of every JSONL line. Large fields use json.RawMessage to avoid unnecessary allocation.

func Parse

func Parse(path string) ([]Entry, error)

Parse reads a JSONL file and returns all entries with computed metadata.

func ParseRaw

func ParseRaw(path string) ([]Entry, [][]byte, error)

ParseRaw reads a JSONL file and returns raw JSON lines alongside entries. This preserves the exact original bytes for faithful rewriting.

func (*Entry) ContentPreview

func (e *Entry) ContentPreview(maxLen int) string

ContentPreview extracts a short text preview from message content.

func (*Entry) HasImages

func (e *Entry) HasImages() bool

HasImages returns true if the message content contains base64 images.

func (*Entry) IsConversational

func (e *Entry) IsConversational() bool

IsConversational returns true for user/assistant types (messages that consume context window).

func (*Entry) ToolUseIDs

func (e *Entry) ToolUseIDs() []string

ToolUseIDs returns tool_use IDs from assistant message content blocks.

type ImageSource

type ImageSource struct {
	Type      string `json:"type"`
	MediaType string `json:"media_type"`
	Data      string `json:"data"`
}

ImageSource holds base64 image data.

type LightStats

type LightStats struct {
	LineCount             int
	AssistantCount        int
	FileSizeBytes         int64
	TypeCounts            map[MessageType]int
	LastUsage             *Usage
	MaxContext            int
	Slug                  string
	ImageCount            int
	ImageBytesEstimate    int64 // total raw bytes of JSONL entries containing images
	CompactionCount       int
	LastCompactionBefore  int
	LastCompactionAfter   int
	TotalInputTokens      int
	TotalOutputTokens     int
	TotalCacheWriteTokens int
	TotalCacheReadTokens  int
	Model                 string
	SignalPercent         int       // 0-100, estimated signal/noise ratio
	EpochAssistantCount   int       // assistant turns since last compaction
	ChainHealthy          bool      // false if active parent chain has missing links
	StartsWithQueueOp     bool      // true if first entry is queue-operation (Mac/desktop indicator)
	FirstTimestamp        time.Time // timestamp of first entry
	LastTimestamp         time.Time // timestamp of last entry
}

LightStats holds minimal stats extracted without full parsing.

func ScanLight

func ScanLight(path string) (*LightStats, error)

ScanLight reads a JSONL file extracting only stats-level data. It avoids full deserialization of large content fields.

type Message

type Message struct {
	Role       string          `json:"role,omitempty"`
	Content    json.RawMessage `json:"content"`
	Model      string          `json:"model,omitempty"`
	ID         string          `json:"id,omitempty"`
	Type       string          `json:"type,omitempty"`
	Usage      *Usage          `json:"usage,omitempty"`
	StopReason *string         `json:"stop_reason,omitempty"`
}

Message holds the role+content from user/assistant messages.

type MessageType

type MessageType string

MessageType enumerates JSONL line types.

const (
	TypeUser                MessageType = "user"
	TypeAssistant           MessageType = "assistant"
	TypeProgress            MessageType = "progress"
	TypeFileHistorySnapshot MessageType = "file-history-snapshot"
	TypeSystem              MessageType = "system"
	TypeQueueOperation      MessageType = "queue-operation"
)

type Usage

type Usage struct {
	InputTokens              int    `json:"input_tokens"`
	OutputTokens             int    `json:"output_tokens"`
	CacheCreationInputTokens int    `json:"cache_creation_input_tokens"`
	CacheReadInputTokens     int    `json:"cache_read_input_tokens"`
	ServiceTier              string `json:"service_tier,omitempty"`
}

Usage holds token counts from assistant messages.

func (*Usage) TotalContextTokens

func (u *Usage) TotalContextTokens() int

TotalContextTokens returns the total context window consumption at the time this assistant message was generated.