Documentation
¶
Overview ¶
Package parser auto-detects and parses session files from multiple tools.
Package parser provides JSONL session file parsing for the recall system.
It parses AI coding assistant session transcripts into structured Go types that can be rendered, searched, and analyzed. The package uses a tool-agnostic Session output type with tool-specific parsers (e.g., ClaudeCodeParser).
Index ¶
- func FindSessions(additionalDirs ...string) ([]*entity.Session, error)
- func FindSessionsForCWD(cwd string, additionalDirs ...string) ([]*entity.Session, error)
- func ParseFile(path string) ([]*entity.Session, error)
- func RegisteredTools() []string
- func ScanDirectory(dir string) ([]*entity.Session, error)
- func ScanDirectoryWithErrors(dir string) ([]*entity.Session, []error, error)
- type ClaudeCodeParser
- type MarkdownSessionParser
- type SessionParser
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func FindSessions ¶
FindSessions searches for session files in common locations.
It checks:
- ~/.claude/projects/ (Claude Code default)
- The specified directory (if provided)
Parameters:
- additionalDirs: Optional additional directories to scan
Returns:
- []*entity.Session: Deduplicated sessions sorted by start time (newest first)
- error: Non-nil if scanning fails (partial results may still be returned)
func FindSessionsForCWD ¶
FindSessionsForCWD searches for sessions matching the given working directory.
Matching is done in order of preference:
- Git remote URL match - if both directories are git repos with the same remote
- Path relative to home - e.g., "WORKSPACE/ctx" matches across users
- Exact CWD match - fallback for non-git, non-home paths
Parameters:
- cwd: Working directory to filter by
- additionalDirs: Optional additional directories to scan
Returns:
- []*entity.Session: Filtered sessions sorted by start time (newest first)
- error: Non-nil if scanning fails
func ParseFile ¶
ParseFile parses a session file using the appropriate parser.
It auto-detects the file format by trying each registered parser.
Parameters:
- path: Path to the session file to parse
Returns:
- []*entity.Session: All sessions found in the file
- error: Non-nil if no parser can handle the file or parsing fails
func RegisteredTools ¶
func RegisteredTools() []string
RegisteredTools returns the list of supported tools.
Returns:
- []string: Tool identifiers for all registered parsers
func ScanDirectory ¶
ScanDirectory recursively scans a directory for session files.
It finds all parseable files, parses them, and aggregates sessions. Sessions are sorted by start time (newest first). Parse errors for individual files are silently ignored; use ScanDirectoryWithErrors if you need to report them.
Parameters:
- dir: Root directory to scan recursively
Returns:
- []*entity.Session: All sessions found, sorted by start time (newest first)
- error: Non-nil if directory traversal fails
func ScanDirectoryWithErrors ¶
ScanDirectoryWithErrors is like ScanDirectory but also returns parse errors.
Use this when you want to report files that failed to parse while still returning successfully parsed sessions.
Parameters:
- dir: Root directory to scan recursively
Returns:
- []*entity.Session: Successfully parsed sessions, sorted by start time
- []error: Errors from files that failed to parse
- error: Non-nil if directory traversal fails
Types ¶
type ClaudeCodeParser ¶
type ClaudeCodeParser struct{}
ClaudeCodeParser parses Claude Code JSONL session files.
Claude Code stores sessions as JSONL files where each line is a self-contained JSON object representing a message. Messages are linked via parentUuid and grouped by sessionId.
func NewClaudeCodeParser ¶
func NewClaudeCodeParser() *ClaudeCodeParser
NewClaudeCodeParser creates a new Claude Code session parser.
Returns:
- *ClaudeCodeParser: A parser instance for Claude Code JSONL files
func (*ClaudeCodeParser) Matches ¶ added in v0.3.0
func (p *ClaudeCodeParser) Matches(path string) bool
Matches returns true if the file appears to be a Claude Code session file.
Checks if the file has a .jsonl extension and contains Claude Code message format (sessionId and slug fields in the first few lines).
Parameters:
- path: File path to check
Returns:
- bool: True if this parser can handle the file
func (*ClaudeCodeParser) ParseFile ¶
func (p *ClaudeCodeParser) ParseFile(path string) ([]*entity.Session, error)
ParseFile reads a Claude Code JSONL file and returns all sessions.
Parses each line as a JSON message, groups messages by session ID, and constructs Session objects with timing, token counts, and message content. Sessions are sorted by start time.
Parameters:
- path: Path to the JSONL file to parse
Returns:
- []*entity.Session: All sessions found in the file, sorted by start time
- error: Non-nil if the file cannot be opened or read
func (*ClaudeCodeParser) ParseLine ¶
ParseLine parses a single JSONL line into a Message.
Unmarshals the JSON, extracts the message content, and converts it to the common Message type. Non-message lines (e.g., file-history-snapshot) are skipped and return nil.
Parameters:
- line: Raw JSONL line bytes to parse
Returns:
- *entity.Message: The parsed message, or nil if the line should be skipped
- string: The session ID this message belongs to
- error: Non-nil if JSON unmarshaling fails
func (*ClaudeCodeParser) Tool ¶
func (p *ClaudeCodeParser) Tool() string
Tool returns the tool identifier for this parser.
Returns:
- string: The identifier "claude-code"
type MarkdownSessionParser ¶ added in v0.8.0
type MarkdownSessionParser struct{}
MarkdownSessionParser parses Markdown session files written by AI agents.
This parser handles the tool-agnostic session format used by non-Claude tools (Copilot, Cursor, Aider, etc.) where the AI agent saves session summaries as structured Markdown in .context/sessions/.
Expected format:
# Session: YYYY-MM-DD - Topic ## What Was Done - ... ## Decisions - ... ## Learnings - ... ## Next Steps - ...
func NewMarkdownSessionParser ¶ added in v0.8.0
func NewMarkdownSessionParser() *MarkdownSessionParser
NewMarkdownSessionParser creates a new Markdown session parser.
Returns:
- *MarkdownSessionParser: A parser instance for Markdown session files
func (*MarkdownSessionParser) Matches ¶ added in v0.8.0
func (p *MarkdownSessionParser) Matches(path string) bool
Matches returns true if the file appears to be a Markdown session file.
Checks if the file has a .md extension and contains a session header in one of the recognized formats.
Parameters:
- path: File path to check
Returns:
- bool: True if this parser can handle the file
func (*MarkdownSessionParser) ParseFile ¶ added in v0.8.0
func (p *MarkdownSessionParser) ParseFile(path string) ([]*entity.Session, error)
ParseFile reads a Markdown session file and returns all sessions.
Each file is treated as a single session. Metadata is extracted from the H1 header (date, topic) and H2 sections (content).
Parameters:
- path: Path to the Markdown file to parse
Returns:
- []*entity.Session: A single-element slice with the parsed session
- error: Non-nil if the file cannot be opened or read
func (*MarkdownSessionParser) ParseLine ¶ added in v0.8.0
ParseLine is not applicable for Markdown files (they are not line-oriented).
Parameters:
- line: Ignored
Returns:
- nil, "", nil always
func (*MarkdownSessionParser) Tool ¶ added in v0.8.0
func (p *MarkdownSessionParser) Tool() string
Tool returns the tool identifier for this parser.
Returns:
- string: The identifier "markdown"
type SessionParser ¶
type SessionParser interface {
// ParseFile reads a session file and returns all sessions found.
// A single file may contain multiple sessions (grouped by session ID).
ParseFile(path string) ([]*entity.Session, error)
// ParseLine parses a single line from a session file.
// Returns nil if the line should be skipped (e.g., non-message lines).
ParseLine(line []byte) (*entity.Message, string, error) // message, sessionID, error
// Matches returns true if this parser can handle the given file.
// Implementations may check file extension, peek at content, etc.
Matches(path string) bool
// Tool returns the tool identifier (e.g., "claude-code", "aider").
Tool() string
}
SessionParser defines the interface for tool-specific session parsers.
Each AI tool (Claude Code, Aider, Cursor) implements this interface to parse its specific format into the common Session type.
func Parser ¶
func Parser(tool string) SessionParser
Parser returns a parser for the specified tool.
Parameters:
- tool: Tool identifier (e.g., "claude-code")
Returns:
- SessionParser: The parser for the tool, or nil if not found
Source Files