go-session/docs/history.md

Project History

Origin

Extracted from forge.lthn.ai/core/go (pkg/session/) on 19 February 2026. The initial extraction provided a working parser that read Claude Code JSONL transcripts into Event arrays and identified the seven supported tool types: Bash, Read, Edit, Write, Grep, Glob, and Task.

Completed Phases

Phase 0 — Hardening and Test Coverage (f40caaa)

Established the test baseline after extraction.

• 67 tests across four test files: parser_test.go, html_test.go, search_test.go, video_test.go.
• Statement coverage: 90.9%.
• parser_test.go covers: ParseTranscript with minimal JSONL, all seven tool types, errors, truncated and malformed lines, large sessions (1 100+ tool pairs), nested array and map result content, ListSessions (empty directory, single session, multiple sessions sorted by timestamp, non-JSONL files ignored, malformed JSONL with mod-time fallback), extractToolInput for all seven tools plus nil input, invalid JSON, and unknown tool fallback, and all three paths of extractResultContent.
• Benchmarks use b.Loop() (Go 1.25+) for accurate timing: 2.2 MB file (5 000 tool pairs), 11 MB file (25 000 tool pairs), ListSessions over 20 files, and Search over 10 files.
• go vet ./... was clean from the outset.

Phase 1 — Parser Robustness (a6fb934)

Added structured diagnostic reporting to ParseTranscript.

• ParseTranscript signature changed to (*Session, *ParseStats, error). Existing callers are unaffected as Go allows ignoring the additional return value with _.
• ParseStats tracks TotalLines, SkippedLines, OrphanedToolCalls, and Warnings.
• Skipped lines append a warning containing the line number and a 100-character preview of the raw content.
• Orphaned tool calls (tool_use entries with no matching tool_result) are counted and their IDs recorded in warnings after the scan completes.
• Truncated final line detection: if the last scanned line failed to unmarshal JSON, a "truncated final line" warning is appended.
• Scanner buffer errors surface directly as a returned error rather than silent truncation.
• Tests added for: clean JSONL (zero counts), three malformed lines mixed with valid content, two orphaned tool calls, file ending mid-JSON object, file ending without a trailing newline, and warning preview truncation for long malformed lines.

Phase 2 — Analytics (a6fb934)

Added analytics.go providing Analyse and FormatAnalytics.

• SessionAnalytics holds duration, active time (sum of tool durations), event count, per-tool call and error counts, success rate, per-tool average and maximum latencies, and estimated token counts (1 token per 4 characters of input and output text).
• Analyse is a pure function with no I/O. Safe to call on a nil *Session.
• FormatAnalytics produces a tabular plain-text summary with a tool breakdown table sorted alphabetically by tool name.
• Tests cover: empty session, nil session, single tool call, mixed tools with errors (success rate and active time calculations), latency averages across three Bash calls and one Read call, and token estimation with known character counts.

Phase 3 — HTML Timeline (9b32678)

Added html.go with RenderHTML (257 lines of code).

• Self-contained dark-theme HTML file with all CSS and JavaScript inline.
• Sticky header showing session short ID (first 8 characters), start timestamp, duration, tool call count, and error count (omitted when zero).
• Events colour-coded by type: Bash (green), errors (red border), user messages (yellow), assistant messages (dim).
• Collapsible detail panels: toggle(i) toggles the open CSS class; arrow rotates 90 degrees using CSS transition. Output capped at 400 px with overflow-y: auto.
• Smart labels per event type: Command (Bash), Target (Read, Glob, Grep), File (Edit, Write), Message (user), Response (assistant).
• Text input and dropdown filter in the sticky header; filterEvents() applies both simultaneously via the data-text attribute.
• Keyboard shortcut: / focuses the search input.
• XSS protection: all user content passed through html.EscapeString including the data-text search attribute.
• Six tests: basic session structure, empty session, error events and status icons, special characters and XSS vectors, invalid output path error, and label-per-tool-type verification.

Known Limitations

extractCommand and Inline # Characters

extractCommand in video.go identifies the description suffix by splitting on the first occurrence of # in the input string. If a Bash command itself contains a literal # (for example inside a quoted string), the command will be truncated at that position in the MP4 tape output. This is a documented behaviour rather than a bug, since extractToolInput always constructs Bash input as command + " # " + description, making a collision possible only in contrived cases.

RenderMP4 Requires an External Binary

RenderMP4 depends on the vhs binary (github.com/charmbracelet/vhs). There is no pure-Go fallback. The function returns a clear error message when vhs is absent. It is not testable in automated CI without the binary present; the test suite covers generateTape (the pure logic) and the error path only.

Search is Sequential

Search parses every session file in the directory sequentially. For directories with many large session files this is the dominant cost. There is no indexing or caching.

Token Estimation

EstimatedInputTokens and EstimatedOutputTokens use a fixed ratio of 4 characters per token. This approximation is suitable for rough comparisons but should not be treated as an accurate token count for billing or quota purposes.

Future Considerations

The following have been identified as potential improvements but are not currently prioritised:

• Parallel search: fan out ParseTranscript calls across goroutines with a result channel to reduce wall time for large directories.
• Persistent index: a lightweight SQLite index or binary cache per session file to avoid re-parsing on every Search or ListSessions call.
• Additional tool types: the parser's extractToolInput fallback handles any unknown tool by listing its JSON keys. Dedicated handling could be added for WebFetch, WebSearch, NotebookEdit, and other tools that appear in Claude Code sessions.
• HTML export options: configurable truncation limits, optional full-output display, and per-event direct links (anchor IDs already exist as evt-{i}).
• VHS alternative: a pure-Go terminal animation renderer to eliminate the vhs dependency for MP4 output.