parser

package
v0.9.1 Latest Latest
Warning

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

 Go to latest Published: Feb 28, 2026 License: MIT Imports: 17 Imported by: 0

Documentation

Overview

ABOUTME: Parses Claude Code JSONL session files into structured session data. ABOUTME: Detects DAG forks in uuid/parentUuid trees and splits large-gap forks into separate sessions.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func CursorSessionID added in v0.9.0 

func CursorSessionID(path string) string

CursorSessionID derives a session ID from a transcript file path by stripping whatever extension is present.

func DecodeCursorProjectDir added in v0.9.0 

func DecodeCursorProjectDir(dirName string) string

DecodeCursorProjectDir extracts a clean project name from a Cursor-style hyphenated directory name. Cursor encodes absolute paths by replacing / and . with hyphens, e.g. "Users-fiona-Documents-mcp-cursor-analytics".

Scans forward from the home-directory root to find the first marker, handling multi-token usernames (e.g. "Users-john-doe-Documents-project").

func ExtractClaudeProjectHints added in v0.4.0 

func ExtractClaudeProjectHints(
	path string,
) (cwd, gitBranch string)

ExtractClaudeProjectHints reads project-identifying metadata from a Claude Code JSONL session file.

func ExtractCwdFromSession 

func ExtractCwdFromSession(path string) string

ExtractCwdFromSession reads the first cwd field from a Claude Code JSONL session file.

func ExtractProjectFromCwd 

func ExtractProjectFromCwd(cwd string) string

ExtractProjectFromCwd extracts a project name from a working directory path. If cwd is inside a git repository (including linked worktrees), this returns the repository root directory name. Otherwise it falls back to the last path component.

func ExtractProjectFromCwdWithBranch added in v0.4.0 

func ExtractProjectFromCwdWithBranch(
	cwd, gitBranch string,
) string

ExtractProjectFromCwdWithBranch extracts a canonical project name from cwd and optionally git branch metadata. Branch is used as a fallback heuristic when the original worktree path no longer exists on disk.

func ExtractTextContent 

func ExtractTextContent(
	content gjson.Result,
) (string, bool, bool, []ParsedToolCall, []ParsedToolResult)

ExtractTextContent extracts readable text from message content. content can be a string or a JSON array of blocks. Returns the text, hasThinking, hasToolUse, tool calls, and tool results.

func GeminiSessionID 

func GeminiSessionID(data []byte) string

GeminiSessionID extracts the sessionId field from raw Gemini session JSON data without fully parsing.

func GetProjectName 

func GetProjectName(dirName string) string

GetProjectName converts an encoded Claude project directory name to a clean project name. Claude encodes paths like /Users/alice/code/my-app as -Users-alice-code-my-app.

func InferRelationshipTypes added in v0.7.0 

func InferRelationshipTypes(results []ParseResult)

InferRelationshipTypes sets RelationshipType on results that have a ParentSessionID but no explicit type. Sessions with an "agent-" prefix are subagents; others are continuations.

func NeedsProjectReparse 

func NeedsProjectReparse(project string) bool

NeedsProjectReparse checks if a stored project name looks like an un-decoded encoded path that should be re-extracted.

func NormalizeName added in v0.6.0 

func NormalizeName(s string) string

NormalizeName converts dashes to underscores for consistent project name formatting.

func NormalizeToolCategory 

func NormalizeToolCategory(rawName string) string

NormalizeToolCategory maps a raw tool name to a normalized category. Categories: Read, Edit, Write, Bash, Grep, Glob, Task, Tool, Other.

func ParseCodexSession 

func ParseCodexSession(
	path, machine string, includeExec bool,
) (*ParsedSession, []ParsedMessage, error)

ParseCodexSession parses a Codex JSONL session file. Returns nil session if the session is non-interactive and includeExec is false.

func ParseCopilotSession added in v0.5.0 

func ParseCopilotSession(
	path, machine string,
) (*ParsedSession, []ParsedMessage, error)

ParseCopilotSession parses a Copilot JSONL session file. Returns (nil, nil, nil) if the file doesn't exist or contains no user/assistant messages.

func ParseCursorSession added in v0.9.0 

func ParseCursorSession(
	path, project, machine string,
) (*ParsedSession, []ParsedMessage, error)

ParseCursorSession parses a Cursor agent transcript file. Transcripts are plain text with "user:" and "assistant:" role markers, tool calls, and thinking blocks.

func ParseGeminiSession 

func ParseGeminiSession(
	path, project, machine string,
) (*ParsedSession, []ParsedMessage, error)

ParseGeminiSession parses a Gemini CLI session JSON file. Unlike Claude/Codex JSONL, each Gemini file is a single JSON document containing all messages.

func ParseOpenCodeSession added in v0.5.0 

func ParseOpenCodeSession(
	dbPath, sessionID, machine string,
) (*ParsedSession, []ParsedMessage, error)

ParseOpenCodeSession parses a single session by ID from the OpenCode database.

Types

type AgentType 

type AgentType string

AgentType identifies the AI agent that produced a session. 

const (
	AgentClaude   AgentType = "claude"
	AgentCodex    AgentType = "codex"
	AgentCopilot  AgentType = "copilot"
	AgentGemini   AgentType = "gemini"
	AgentOpenCode AgentType = "opencode"
	AgentCursor   AgentType = "cursor"
)

type FileInfo 

type FileInfo struct {
	Path  string
	Size  int64
	Mtime int64
	Hash  string
}

FileInfo holds file system metadata for a session source file.

type OpenCodeSession added in v0.5.0 

type OpenCodeSession struct {
	Session  ParsedSession
	Messages []ParsedMessage
}

OpenCodeSession bundles a parsed session with its messages.

func ParseOpenCodeDB added in v0.5.0 

func ParseOpenCodeDB(
	dbPath, machine string,
) ([]OpenCodeSession, error)

ParseOpenCodeDB opens the OpenCode SQLite database read-only and returns all sessions with messages.

type OpenCodeSessionMeta added in v0.5.0 

type OpenCodeSessionMeta struct {
	SessionID   string
	VirtualPath string
	FileMtime   int64
}

OpenCodeSessionMeta is lightweight metadata for a session, used to detect changes without parsing messages or parts.

func ListOpenCodeSessionMeta added in v0.5.0 

func ListOpenCodeSessionMeta(
	dbPath string,
) ([]OpenCodeSessionMeta, error)

ListOpenCodeSessionMeta returns lightweight metadata for all sessions without parsing messages or parts. Used by the sync engine to detect which sessions have changed.

type ParseResult added in v0.7.0 

type ParseResult struct {
	Session  ParsedSession
	Messages []ParsedMessage
}

ParseResult pairs a parsed session with its messages.

func ParseClaudeSession 

func ParseClaudeSession(
	path, project, machine string,
) ([]ParseResult, error)

ParseClaudeSession parses a Claude Code JSONL session file. Returns one or more ParseResult structs (multiple when forks are detected in the uuid/parentUuid DAG).

type ParsedMessage 

type ParsedMessage struct {
	Ordinal       int
	Role          RoleType
	Content       string
	Timestamp     time.Time
	HasThinking   bool
	HasToolUse    bool
	ContentLength int
	ToolCalls     []ParsedToolCall
	ToolResults   []ParsedToolResult
}

ParsedMessage holds a single extracted message.

type ParsedSession 

type ParsedSession struct {
	ID               string
	Project          string
	Machine          string
	Agent            AgentType
	ParentSessionID  string
	RelationshipType RelationshipType
	FirstMessage     string
	StartedAt        time.Time
	EndedAt          time.Time
	MessageCount     int
	UserMessageCount int
	File             FileInfo
}

ParsedSession holds session metadata extracted from a JSONL file.

type ParsedToolCall 

type ParsedToolCall struct {
	ToolUseID         string // tool_use block id from session data
	ToolName          string // raw name from session data
	Category          string // normalized: Read, Edit, Write, Bash, etc.
	InputJSON         string // raw JSON of the input object
	SkillName         string // skill name when ToolName is "Skill"
	SubagentSessionID string // linked subagent session file (e.g. "agent-{task_id}")
}

ParsedToolCall holds a single tool invocation extracted from a message.

type ParsedToolResult added in v0.4.0 

type ParsedToolResult struct {
	ToolUseID     string
	ContentLength int
}

ParsedToolResult holds metadata about a tool result block in a user message (the response to a prior tool_use).

type RelationshipType added in v0.7.0 

type RelationshipType string

RelationshipType describes how a session relates to its parent. 

const (
	RelNone         RelationshipType = ""
	RelContinuation RelationshipType = "continuation"
	RelSubagent     RelationshipType = "subagent"
	RelFork         RelationshipType = "fork"
)

type RoleType 

type RoleType string

RoleType identifies the role of a message sender. 

const (
	RoleUser      RoleType = "user"
	RoleAssistant RoleType = "assistant"
)

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.