Guide

How to read a Claude Code session log

Claude Code writes every session to disk as it happens. Here is where the file lives, what is in it, how to read it without a tool, and what the record leaves out.

What is in the file

Claude Code stores every session as a JSONL file, one JSON object per line, under ~/.claude/projects/<encoded-project-path>/<session-id>.jsonl. The project folder is your working directory path with non-alphanumeric characters replaced by hyphens.1 Each line is one event: a user turn, an assistant reply, a tool call, a tool result, or a system event. The file is append-only; new events are new lines.2

Each event carries top-level fields such as type, uuid, parentUuid, timestamp, sessionId, cwd, gitBranch and version. Inside message.content are content blocks: text, thinking, tool_use with an id, a name and its input, and tool_result referencing the tool_use_id it answers.2 That is enough structure to rebuild the whole session in order: which prompt led to which tool call, what came back, and what the agent said next.

Reading it by hand

Find the folder for your project, sort by modification time, and open the newest file. Filter lines by type to see only user turns, or only tool results. The parentUuid chain is the conversation thread; the gitBranch field tells you where you were when each turn happened. A short script that prints timestamp, type and the first line of each text block gives you a readable transcript in a minute.

There are also community tools that render transcripts as pages, such as Simon Willison's claude-code-transcripts.3 They answer the question "what was said", which is the right first question.

What a transcript does not tell you

A transcript is the record of what happened, in order. It does not say which prompt was the one that went wrong, which correction repaired it, where the time went, or whether the build ended up where you said it should. Those are readings of the record, and they are the part that takes the work.

That is the part Cartographer does. It reads the same file through an adapter that turns it into a plain stream of events, reads every prompt for what act it performs and what it anchors to, and hands the agent that was in the session a brief. The agent writes the map: chapters, then moves, each with what you did, what happened, what it meant, how it turned out and how you responded, each citing the timeline it rests on. How it works has the detail, and the demo replay shows a real build read this way.

Questions

Where does Claude Code keep session history?

Under your home folder, in ~/.claude/projects/, one folder per project, one JSONL file per session. The folder name is the project path with non-alphanumeric characters replaced by hyphens.

Can I read the file without a tool?

Yes. It is plain text, one JSON object per line. Any editor opens it, and a line of jq or a few lines of Python turn it into something readable.

Does Cartographer copy my transcripts?

No. It reads them where they are and writes maps, briefs and replays under ~/.cartographer. Raw transcripts are never copied there, and secrets are redacted before anything is written.

Does any of this leave my machine?

Not through Cartographer. The dashboard binds to 127.0.0.1, and the only network call the tool makes is the installer downloading it.

Sources

  1. Claude Code documentation. Explore the .claude directory.
  2. Claude Code documentation. Manage sessions.
  3. Simon Willison. claude-code-transcripts, on GitHub.