reading-session-transcripts

name	reading-session-transcripts
description	Resolves DorkOS session URLs to JSONL transcript files on disk and reads them. Use when the user shares a session URL, mentions "read this transcript", "read this chat", or references a DorkOS session they want analyzed.

Reading Session Transcripts

Overview

DorkOS sessions from the claude-code runtime are backed by Claude SDK JSONL transcript files on disk. When a user shares a session URL or asks you to read a transcript/chat, resolve the URL to the file path and read it directly.

Caveat: session storage is runtime-owned (ADR-0310). This resolution logic only applies to claude-code sessions — sessions from the codex or opencode runtimes live in their own runtime's store, not in ~/.claude/projects/.

When to Use

• User shares a URL like http://localhost:*/session?session=...&dir=...
• User says "read this transcript", "read this chat", "look at this session", or similar
• User pastes one or more session URLs inline with other instructions
• User references a session ID and directory path

URL Resolution

Given a URL like:

http://localhost:6241/session?session=05da5015-ed83-491c-a07b-10b21379c3e4&dir=%2FUsers%2Fjane%2FMy+Project

Step 1: Extract Parameters

• Session ID: from session query param → 05da5015-ed83-491c-a07b-10b21379c3e4
• Directory: from dir query param, URL-decoded → /Users/jane/My Project

Step 2: Slugify the Directory

Replace all non-alphanumeric, non-dash characters with dashes:

/Users/jane/My Project → -Users-jane-My-Project

This matches the SDK's getProjectSlug() in apps/server/src/services/runtimes/claude-code/sessions/transcript-reader.ts.

Step 3: Construct the File Path

~/.claude/projects/{slug}/{sessionId}.jsonl

Full example:

/Users/doriancollier/.claude/projects/-Users-jane-My-Project/05da5015-ed83-491c-a07b-10b21379c3e4.jsonl

Step 4: Read the File

Use the Read tool on the resolved path. The file contains one JSON object per line — the full conversation transcript including messages, tool calls, and results.

Multiple Transcripts

When the user provides multiple URLs, resolve and read each one. They may want comparison, analysis, or context from several sessions.

Edge Cases

• URL uses a non-standard port: The port doesn't matter — only session and dir query params are needed
• Spaces in directory: URL-encode as + or %20 — both decode correctly
• File not found: The session may have been deleted, the directory path may be wrong, or — likely — the session belongs to another runtime (codex or opencode, ADR-0310), whose transcripts don't live in ~/.claude/projects/. Never fail silently: report the resolved path and say the session may belong to a non-claude-code runtime.
• Session ID without URL: If the user provides just a session ID, ask for the directory (or check the current working directory slug).