What Claude Session Logs Are

The Useful Definition

A Claude session log is the durable record of an agent run: the user prompt, the assistant responses, the tool calls the agent requested, and the results that came back. Anthropic describes a session as conversation history accumulated while an agent works, and the Agent SDK writes that state automatically so it can be resumed later.

That makes the transcript a review artifact. It lets a human reconstruct what the agent believed, which commands or tools it asked to run, which files it inspected, and how the final answer was produced. It is especially valuable when a run spans multiple turns, subagents, approvals, or restarts.

What It Does Not Prove

A transcript is not a build record, a git object, a policy decision by itself, or an authoritative billing invoice. It preserves conversation continuity. It does not freeze the filesystem. If an agent says tests passed, the transcript is one piece of evidence; the test log, commit diff, and CI result are the stronger operational artifacts.

This distinction matters during incident review. When a surprising change appears, start with the transcript to find intent and sequence. Then verify the final state with repository evidence. If those conflict, trust the current file tree and build outputs over the natural-language summary.

Where The Artifact Lives

For Agent SDK usage, Anthropic documents local transcript storage as JSONL under ~/.claude/projects/. That path is important because many tools and internal workflows treat JSONL as the raw source and generate Markdown, HTML, dashboards, or summaries from it.

In CLI workflows, the exact file path is often surfaced to hooks as transcript_path. That field is useful for copying, indexing, or validating a transcript at lifecycle boundaries, but it should still be treated as sensitive local data.

The Review Habit

The best practical habit is to name sessions, preserve the transcript for work that matters, and link transcript-derived notes to the commit, issue, PR, or incident record. The CLI supports session naming and resume flows, which turns a transcript from a hidden file into a durable reference point.

For general Claude Code workflow guidance, use Claude Ships Code. Claude Logs stays focused on the evidence trail after the work has happened.

• Capture the session ID or name when a run starts.
• Store the final git SHA, diff summary, and test command beside transcript-derived notes.
• Do not share raw transcripts externally until prompts, tool inputs, secrets, and personal data have been reviewed.