Accessing Claude Code Previous Sessions via JSONL Transcripts

Claude Code stores all your conversation history locally as JSONL files. If you need to reference what you discussed in a previous session - or build tools on top of that history - here is where to find them and how to use them.

Where the Files Live

Transcripts are stored in ~/.claude/projects/ organized by your project's filesystem path. Each conversation gets its own .jsonl file with a timestamp-based name. The directory structure mirrors your project paths, so a project at /Users/you/myapp would have its transcripts under a corresponding subdirectory.

The JSONL Format

Each line in the file is a JSON object representing one event in the conversation. Events include user messages, assistant responses, tool calls (file reads, edits, bash commands), and tool results. The structure is nested - a single assistant turn might contain multiple tool uses with their results on subsequent lines.

Reading Specific Transcripts

You can tell Claude Code to read specific past transcripts. Just reference the file path and ask it to parse the conversation. This is useful when you want to continue work from a previous session or understand what decisions were made and why.

However, parsing raw transcripts is painful. The JSONL format is verbose, with tool calls containing full file contents and bash outputs. A single conversation can easily be tens of thousands of lines. You will want to filter for just the user and assistant message content, skipping tool call details.

Practical Script for Parsing

A simple approach is to extract just the conversational turns:

import json

def extract_messages(jsonl_path):
    messages = []
    with open(jsonl_path) as f:
        for line in f:
            event = json.loads(line)
            if event.get("type") in ("human", "assistant"):
                messages.append(event)
    return messages

This gives you the high-level conversation flow without the noise of every file read and bash command.

Building on Top of Transcripts

Teams build dashboards that track what agents worked on, how long tasks took, and which files were modified. The data is all there in the JSONL files - you just need to parse it into something useful.

More on This Topic

• Parsing Claude Code JSONL Format for macOS Dev Tools
• MCP Servers for Raw Data Context and Transcripts
• Claude Code Auto Memory vs Explicit Specs

Fazm is an open source macOS AI agent. Open source on GitHub.