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).