Session Transcripts for Debugging Agent Workflows

What session transcripts are

Every Agent SDK session generates a .jsonl file. It captures everything that happened: every message, every tool call with its inputs and outputs, every token count, every cost event. The same system that Claude Code uses — same engine, same storage format.

These files are not logs in the traditional sense. They are structured records of the agent's complete execution. Every decision the agent made, every tool it called, every response it generated is in there.

For debugging, they are more useful than console logs. For auditing, they are more complete than anything you would build manually.

Where the files live

The transcript files are stored in your global .claude folder. On most systems, that is:

~/.claude/projects/<project-id>/

Each transcript is named with a session ID and .jsonl extension. If you are running many development sessions, you will accumulate dozens of these files.

The JSONL format

A JSONL file is a JSON file where each line is a separate JSON object. Each line in a transcript file is one message from the agent's execution — a system initialization event, a tool call, a text response, a result.

Opening the file in a text editor can be overwhelming. The structure is dense and not intended for human reading. Use option-Z on Mac or equivalent word wrap to make the lines readable, but even then the raw content is hard to parse.

The right approach: use an agent to read it.

Using an agent to read transcripts

The most practical way to work with transcript files is to give the path to Claude Code or your coding agent and ask it to explain what happened.

Find the session you are looking for:

ls ~/.claude/projects/ -la

Or search for content within the files:

grep -r "haiku" ~/.claude/projects/ -l

Once you have the file path, tell your coding agent: "Read this transcript file and explain what the agent did. I had a bug where [describe the problem] — do you see anything in the execution that explains it?"

The agent reads the JSONL, parses the message sequence, and gives you a readable account of what happened. It can identify where tool calls failed, where the agent made unexpected decisions, and where inputs or outputs diverged from what you expected.

What to look for when debugging

Common issues that transcripts reveal:

Unexpected tool calls. The agent called a tool you did not expect. The transcript shows the exact tool name, the exact inputs it used, and what it got back. If the inputs are wrong, the bug is in how your prompt described the task.

Tool failures. A tool ran but returned an error. The transcript captures the full error response. Debugging against the actual error message is faster than guessing.

Session resumption issues. The agent started fresh when it should have resumed. The system initialization message shows whether the resume parameter was passed correctly.

Model behavior discrepancies. The agent took 15 turns on a task you expected to finish in 3. The turn count is in the result message. The tool calls in between show exactly where the extra work happened.

Building agent-assisted debugging into your workflow

The pattern:

1. Agent behaves unexpectedly during development 2. Find the transcript file for that session 3. Give the file path to your coding agent 4. Ask it to explain the execution and identify the issue

This is faster than adding console logs, re-running the agent, and parsing output manually. The transcript already has everything.

For production agents, consider building a simple transcript viewer that lets you search sessions by thread ID, user, or time range. With the session ID from your database mapping and the session ID in the transcript filename, connecting the two is straightforward.

> Power user note: Transcript files are the same format whether generated by Claude Code or the Agent SDK. If you are debugging an agent you built with the SDK while also using Claude Code for development work, you can use Claude Code itself to read and analyze the SDK agent's transcripts. The shared format makes the tooling interchangeable.

---

Author: FractionalSkill