Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 3 additions & 1 deletion .gitignore
Original file line number Diff line number Diff line change
@@ -1,2 +1,4 @@
.core/
.idea/
.vscode/
*.log
.core/
4 changes: 2 additions & 2 deletions CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Claude Code JSONL transcript parser, analytics engine, and HTML/video renderer. Module: `forge.lthn.ai/core/go-session`
Claude Code JSONL transcript parser, analytics engine, and HTML/video renderer. Module: `dappco.re/go/core/session`

## Commands

Expand Down Expand Up @@ -45,6 +45,6 @@ Coverage target: maintain ≥90.9%.
- Explicit types on all function signatures and struct fields
- `go test ./...` and `go vet ./...` must pass before commit
- SPDX header on all source files: `// SPDX-Licence-Identifier: EUPL-1.2`
- Error handling: all errors must use `coreerr.E(op, msg, err)` from `forge.lthn.ai/core/go-log`, never `fmt.Errorf` or `errors.New`
- Error handling: all errors must use `coreerr.E(op, msg, err)` from `dappco.re/go/core/log`, never `fmt.Errorf` or `errors.New`
- Conventional commits: `type(scope): description`
- Co-Author trailer: `Co-Authored-By: Virgil <virgil@lethean.io>`
181 changes: 87 additions & 94 deletions CONTEXT.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,123 +2,73 @@

> Relevant knowledge from OpenBrain.

## 1. go-session [convention] (score: 0.636)
### 1. go-session [service] (score: 0.080)

Documentation
[go-session] Licence

- `/Users/snider/Code/go-session/docs/architecture.md` — JSONL format, parsing pipeline, event types, analytics, HTML rendering, XSS protection
- `/Users/snider/Code/go-session/docs/development.md` — prerequisites, build/test commands, test patterns, coding standards
- `/Users/snider/Code/go-session/docs/history.md` — completed phases, known limitations, future considerations
EUPL-1.2

## 2. go-session [service] (score: 0.604)
### 2. go-session [convention] (score: 0.021)

[go-session] Pages
Coding Standards

- [[Session-Format]] -- JSONL structure, parsing logic, and event types
- [[Rendering]] -- HTML timeline and MP4 video output
- UK English throughout (colour, licence, initialise)
- `declare(strict_types=1)` equivalent: explicit types on all signatures
- `go test ./...` must pass before commit
- `go vet ./...` must be clean before commit
- SPDX-Licence-Identifier: EUPL-1.2 header on all source files
- Conventional commits: `type(scope): description`
- Co-Author: `Co-Authored-By: Virgil <virgil@lethean.io>`
- Test naming: `TestFunctionName_Context_Good/Bad/Ugly`
- New tool types: add struct in `parser.go`, case in `extractToolInput`, label in `html.go`, tape entry in `video.go`, and tests in `parser_test.go`

## 3. go-session [service] (score: 0.563)
### 3. go-session [service] (score: 0.006)

[go-session] Core Types
[go-session] Labels

```go
// Session holds parsed metadata and events from a transcript.
type Session struct {
ID string
Path string
StartTime time.Time
EndTime time.Time
Events []Event
}
The input label adapts to the tool type:

// Event represents a single action in the session timeline.
type Event struct {
Timestamp time.Time
Type string // "tool_use", "user", "assistant", "error"
Tool string // "Bash", "Read", "Edit", "Write", "Grep", "Glob", etc.
ToolID string
Input string
Output string
Duration time.Duration
Success bool
ErrorMsg string
}
```
- **Bash**: "Command"
- **Read, Glob, Grep**: "Target"
- **Edit, Write**: "File"
- **User messages**: "Message"
- **Assistant**: "Response"

## 4. go-session [service] (score: 0.560)
### 4. go-session [service] (score: -0.002)

[go-session] Installation

```bash
go get forge.lthn.ai/core/go-session@latest
go get dappco.re/go/core/session@latest
```

## 5. go-session [service] (score: 0.557)
### 5. go-session [convention] (score: -0.004)

[go-session] API Summary

| Function | Description |
|----------|-------------|
| `ListSessions(dir)` | List all `.jsonl` sessions in a directory, sorted newest first |
| `ParseTranscript(path)` | Parse a JSONL file into a structured `*Session` |
| `Search(dir, query)` | Search tool events across all sessions |
| `RenderHTML(sess, path)` | Generate self-contained HTML timeline |
| `RenderMP4(sess, path)` | Generate MP4 video via VHS (Charmbracelet) |

## 6. go-session [service] (score: 0.536)

[go-session] Prerequisites
Commands

```bash
go install github.com/charmbracelet/vhs@latest
go test ./... # Run all tests
go test -v -run Name # Run single test
go vet ./... # Vet the package
```

## 7. go-session [service] (score: 0.524)
### 6. go-session [service] (score: -0.023)

[go-session] Quick Start
[go-session] Event Card Layout

```go
package main

import (
"fmt"
"log"

"forge.lthn.ai/core/go-session"
)

func main() {
// Parse a single transcript
sess, err := session.ParseTranscript("~/.claude/projects/abc123.jsonl")
if err != nil {
log.Fatal(err)
}
fmt.Printf("Session %s: %d events over %s\n",
sess.ID, len(sess.Events), sess.EndTime.Sub(sess.StartTime))

// Render to interactive HTML
if err := session.RenderHTML(sess, "timeline.html"); err != nil {
log.Fatal(err)
}
}
```
Each card displays:

## 8. go-session [service] (score: 0.523)
| Element | Description |
|---------|-------------|
| Timestamp | `HH:MM:SS` of the event |
| Tool badge | Colour-coded tool name |
| Input summary | Truncated to 120 characters |
| Duration | Formatted as ms/s/min/hr |
| Status icon | Green tick or red cross for tool calls |

[go-session] Usage
Clicking a card expands it to show the full input (labelled contextually as Command, Message, File, or Target) and the complete output.

```go
sess, err := session.ParseTranscript("session.jsonl")
if err != nil {
log.Fatal(err)
}

if err := session.RenderMP4(sess, "output/session.mp4"); err != nil {
log.Fatal(err)
}
```

## 9. go-session [service] (score: 0.520)
### 7. go-session [service] (score: -0.024)

[go-session] Tape Configuration

Expand All @@ -135,9 +85,52 @@ Shell bash

See also: [[Home]] | [[Session-Format]]

## 10. go-session [service] (score: 0.509)
### 8. go-session [service] (score: -0.031)

[go-session] Prerequisites

```bash
go install github.com/charmbracelet/vhs@latest
```

### 9. go-session [service] (score: -0.040)

[go-session] How It Works

[go-session] Rendering
1. A VHS `.tape` script is generated from the session events
2. The tape uses the Catppuccin Mocha theme at 1400x800 resolution
3. Only `tool_use` events are rendered:
- **Bash**: Shows the command being typed, abbreviated output, and a status indicator
- **Read/Edit/Write**: Shows a comment line with the file path
- **Task**: Shows an "Agent:" comment with the task description
4. Each event includes a brief pause for readability
5. VHS renders the tape to the specified MP4 path

go-session provides two output formats for visualising parsed sessions: a self-contained HTML timeline and an MP4 video rendered via Charmbracelet VHS.
### 10. go-session [service] (score: -0.044)

[go-session] Core Types

```go
// Session holds parsed metadata and events from a transcript.
type Session struct {
ID string
Path string
StartTime time.Time
EndTime time.Time
Events []Event
}

// Event represents a single action in the session timeline.
type Event struct {
Timestamp time.Time
Type string // "tool_use", "user", "assistant", "error"
Tool string // "Bash", "Read", "Edit", "Write", "Grep", "Glob", etc.
ToolID string
Input string
Output string
Duration time.Duration
Success bool
ErrorMsg string
}
```

34 changes: 31 additions & 3 deletions PROMPT.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,11 +8,21 @@ Read RECENT.md for recent changes.

Work in the src/ directory. Follow the conventions in CLAUDE.md.

## SANDBOX BOUNDARY (HARD LIMIT)

You are restricted to the current directory and its subdirectories ONLY.
- Do NOT use absolute paths (e.g., /Users/..., /home/...)
- Do NOT navigate with cd .. or cd /
- Do NOT edit files outside this repository
- Do NOT access parent directories or other repos
- Any path in Edit/Write tool calls MUST be relative to the current directory
Violation of these rules will cause your work to be rejected.

## Workflow

If PLAN.md exists, you MUST work through it phase by phase:
1. Complete all tasks in the current phase
2. STOP and commit before moving on: type(scope): phase N - description
2. STOP and commit before moving on: `type(scope): phase N - description`
3. Only then start the next phase
4. If you are blocked or unsure, write BLOCKED.md explaining the question and stop
5. Do NOT skip phases or combine multiple phases into one commit
Expand All @@ -21,9 +31,27 @@ Each phase = one commit. This is not optional.

If no PLAN.md, complete TODO.md as a single unit of work.

## Closeout Sequence (MANDATORY before final commit)

After completing your work, you MUST run this polish cycle using the core plugin agents:

### Pass 1: Code Review
Use the Agent tool to launch the `core:agent-task-code-review` agent. It will review all your changes for bugs, security issues, and convention violations. Fix ALL findings rated >= 50 confidence before proceeding.

### Pass 2: Build + Test
Run the test suite (`go test ./...` or `composer test`). Fix any failures.

### Pass 3: Simplify
Use the Agent tool to launch the `core:agent-task-code-simplifier` agent. It will consolidate duplicates, remove dead code, and flatten complexity. Let it work, then verify the build still passes.

### Pass 4: Final Review
Run the `core:agent-task-code-review` agent ONE MORE TIME on the simplified code. If clean, commit. If findings remain, fix and re-check.

Each pass catches things the previous one introduced. Do NOT skip passes. The goal: zero findings on the final review.

## Commit Convention

Commit message format: type(scope): description
Co-Author: Co-Authored-By: Virgil <virgil@lethean.io>
Commit message format: `type(scope): description`
Co-Author: `Co-Authored-By: Virgil <virgil@lethean.io>`

Do NOT push. Commit only — a reviewer will verify and push.
8 changes: 4 additions & 4 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,19 +1,19 @@
[![Go Reference](https://pkg.go.dev/badge/forge.lthn.ai/core/go-session.svg)](https://pkg.go.dev/forge.lthn.ai/core/go-session)
[![Go Reference](https://pkg.go.dev/badge/dappco.re/go/core/session.svg)](https://pkg.go.dev/dappco.re/go/core/session)
[![License: EUPL-1.2](https://img.shields.io/badge/License-EUPL--1.2-blue.svg)](LICENSE.md)
[![Go Version](https://img.shields.io/badge/Go-1.26-00ADD8?style=flat&logo=go)](go.mod)

# go-session

Claude Code JSONL transcript parser, analytics engine, and HTML timeline renderer. Parses Claude Code session files into structured event arrays (tool calls with round-trip durations, user and assistant messages), computes per-tool analytics (call counts, error rates, average and peak latency, estimated token usage), renders self-contained HTML timelines with collapsible panels and client-side search, and generates VHS tape scripts for MP4 video output. No external runtime dependencies — stdlib only.

**Module**: `forge.lthn.ai/core/go-session`
**Module**: `dappco.re/go/core/session`
**Licence**: EUPL-1.2
**Language**: Go 1.25
**Language**: Go 1.26

## Quick Start

```go
import "forge.lthn.ai/core/go-session"
import "dappco.re/go/core/session"

sess, stats, err := session.ParseTranscript("/path/to/session.jsonl")
analytics := session.Analyse(sess)
Expand Down
14 changes: 7 additions & 7 deletions RECENT.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,12 @@
# Recent Changes

```text
```
fb672f3 Merge pull request '[agent/claude:sonnet] Fix CodeRabbit findings. These are mostly markdown linting i...' (#3) from agent/fix-coderabbit-findings--these-are-mostl into main
73e627f fix(coderabbit): address markdown linting findings
66fbb42 Merge pull request '[agent/claude:opus] DX audit and fix. 1) Review CLAUDE.md — update any outdate...' (#2) from agent/dx-audit-and-fix--1--review-claude-md into main
7f0a7ed fix(dx): audit and fix error handling, SPDX headers, coverage, and CLAUDE.md
11e3bb3 Merge pull request '[agent/claude:opus] DX audit and fix. 1) Review CLAUDE.md — update any outdate...' (#1) from agent/dx-audit-and-fix--1--review-claude-md into main
c769692 fix(dx): fix coreerr.E() signatures, add SPDX headers and tests
55ceab4 refactor(error-handling): replace fmt.Errorf and errors.New with coreerr.E()
a07e41a chore: add .core/ and .idea/ to .gitignore
50d1c3f docs: add CLAUDE.md project instructions
Expand All @@ -15,10 +21,4 @@ cb7b5de chore: sync workspace dependency versions
1458694 refactor: apply go fix modernizers for Go 1.26
5dc4078 chore: bump go directive to 1.26.0
325fddd docs: add README with quick start and docs links
91e7cdb Merge remote-tracking branch 'origin/main'
3e00791 docs: graduate TODO/FINDINGS into production documentation
1031905 feat(parser): add robustness for truncated JSONL and malformed lines
8e91626 docs: mark Phase 3 timeline UI as complete
9b32678 docs(todo): mark Phase 1+2 complete with commit hash a6fb934
a6fb934 feat(parser): Phase 1+2 — parse stats, truncation detection, session analytics
```
18 changes: 13 additions & 5 deletions TODO.md
Original file line number Diff line number Diff line change
@@ -1,8 +1,16 @@
# TASK: Replace ALL fmt.Errorf and errors.New in production code with coreerr.E() from go-log. ~8 instances. Import coreerr "forge.lthn.ai/core/go-log". Run tests after.
# TODO

**Repo:** core/go-session
**Status:** ready
## Task
Update go.mod require lines from forge.lthn.ai to dappco.re paths. Update versions: core v0.5.0, log v0.1.0, io v0.2.0. Update all .go import paths. Run go mod tidy and go build ./...

## Objective
> **Status:** Complete. All module paths migrated to `dappco.re/go/core/...`.

## Checklist
- [x] Read and understand the codebase
- [x] Implement the required changes
- [x] Run build: `go build ./...`
- [x] Run tests: `go test ./...`
- [ ] Commit with conventional commit message

## Context

Replace ALL fmt.Errorf and errors.New in production code with coreerr.E() from go-log. ~8 instances. Import coreerr "forge.lthn.ai/core/go-log". Run tests after.
2 changes: 1 addition & 1 deletion docs/architecture.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ description: Internals of go-session -- JSONL format, parsing pipeline, event mo

# Architecture

Module: `forge.lthn.ai/core/go-session`
Module: `dappco.re/go/core/session`

## Overview

Expand Down
2 changes: 1 addition & 1 deletion docs/development.md
Original file line number Diff line number Diff line change
Expand Up @@ -210,7 +210,7 @@ Co-Authored-By: Virgil <virgil@lethean.io>

## Module Path and Go Workspace

The module path is `forge.lthn.ai/core/go-session`. If this package is used within a Go workspace, add it with:
The module path is `dappco.re/go/core/session`. If this package is used within a Go workspace, add it with:

```bash
go work use ./go-session
Expand Down
2 changes: 1 addition & 1 deletion docs/history.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

## 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.
Extracted from `dappco.re/go/core` (`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

Expand Down
Loading