Course B · Module B2 Going Agentic · Lesson 13 of 18

Reading Session Logs

The transcript of every step your agent took is already on disk. Learning to read it turns a black box into something you can supervise and fix.

~12 min · Have a terminal open · Prereq: B12 Using Subagents

You deployed an agent. It ran. But what exactly did it do? If you can't answer that, you don't really own it — you just hope it did the right thing. Session logs are your answer. Claude Code writes a complete transcript of every session to disk automatically: the goal you set, every tool it called, every result it got back, every piece of reasoning it did in between. Your single win: by the end of this lesson you'll know where to find that file, how to read it, and how to use it to find exactly where things went sideways — the same debugging loop you learned in Course A, now applied to agents.

What a session log contains

A session log is a line-by-line record of the agent's full loop. Each entry is one of these four types:

Goal / promptThe original instruction you gave — exactly as the agent received it. The starting point for any audit.

ReasoningThe model's "thinking" before it acts — what it decided to do next and why. This is where you spot misunderstandings early.

Tool callWhich tool it called and what arguments it passed. This is the action audit line — the exact thing it did to the outside world.

Tool resultWhat came back. Did the search return good results? Did the file write succeed? The result shapes every step that follows.

Claude Code stores sessions as .jsonl files (one JSON object per line) under ~/.claude/projects/<your-project>/. You can open them in any text editor, or pipe them through a formatter to make them readable.

# Find your session files
ls ~/.claude/projects/

# Pretty-print the latest session log
cat ~/.claude/projects/<project>/<session>.jsonl \
  | python3 -m json.tool

Reading a log to find where it went wrong

This is the debugging loop from Course A, applied to agents. Same posture — start at the point of failure and work backwards:

Find the wrong output. Where did the agent produce something you didn't want — or stop before it should have?
Find that moment in the log. Scan backwards from the end. Look for the tool call or reasoning entry right before things went off.
Read the result that preceded it. What did the tool return? A bad search result, an empty file, an error message? That result fed the next decision.
Trace back to the root. Was the tool call itself wrong (bad arguments)? Was the reasoning step flawed (misread the result)? Was the original goal too vague? That's your fix point.

A session log is like flight-recorder data. After an incident, investigators don't guess — they read the tape: altitude, heading, control inputs, cockpit conversation, one second at a time, working from the moment of failure backwards to the cause. You're doing the same thing. The log is your tape.

Auditing tool calls for safety

Tool calls are the lines in the log you must review for any agent that touches live data — a database, email, or external API. Before you declare an agent safe to run unsupervised, go through at least one full session log and ask for every tool call:

For each tool call in the log, check:

Did it call the right tool? Not a broader, more destructive one than needed.
Were the arguments right? The correct file, the right recipient, the intended record — not a wildcard that touched more than you expected.
Was the action reversible? Reads are safe; writes and sends are not. For irreversible actions, was there a human checkpoint before it fired?
Did it stop when it should have? The loop ends on task completion, not when it runs out of things to try.

Logs turn "trust me" into "I can verify." An agent without logs is a black box — you accept whatever it did on faith. An agent whose logs you read regularly is a supervised employee. That's the difference between deploying nervously and deploying confidently. Read at least the first three sessions of any new agent before you leave it to run alone.

Check yourself

Answer before opening — recalling it now is what makes it stick.

Your agent sent an email to the wrong address. Where in the session log do you look first?

The tool call entry for send_email — specifically the arguments it passed. That line will show you exactly what address the agent passed to the tool. Then look one entry earlier at the reasoning step: where did it get that address from? Was it pulled from a bad search result, a misread file, or an ambiguous goal? Trace back from the call to the root.

Where does Claude Code store session log files?

Under ~/.claude/projects/<project-name>/ as .jsonl files — one JSON object per line, one file per session. You can open them in any text editor or format them with a JSON tool.

Why should you audit tool calls specifically, rather than just reading the final output?

Because the final output only tells you what the agent produced — not what it did along the way. A tool call is an action on the outside world: it sent an email, deleted a record, ran a query. The final answer can look correct while a tool call mid-run did something unintended. Auditing tool calls is how you catch side-effects, not just bad answers.