How to debug a Claude Code session
Restore the detail Claude Code's terminal collapsed. The middle ground between one-line summaries and the --verbose JSON firehose.
Claude Code debugging used to be straightforward: the terminal printed every file read, every pattern searched, every line edited. Since v2.1.20, that detail was replaced with opaque summaries like Read 3 files. The only built-in alternative is --verbose, which dumps raw JSON.
claude-devtools restores the middle ground. It is a dedicated debugging tool for Claude Code that reads your session transcripts and exposes:
- Exact tool call inputs and outputs — file paths, regex patterns, bash commands, diffs
- Extended thinking content — Claude's internal reasoning for each turn
- Token attribution per turn — what consumed context, broken down by category
- Subagent execution trees — nested agent calls rendered as expandable cards
- Compaction events — when context was compressed and what was lost
When a Claude Code session goes wrong — wrong file edited, context filled unexpectedly, subagent misbehaved — this is the tool you reach for.
To start: install claude-devtools, open the app, pick a project from the dashboard, and select a session from the sidebar. The full transcript renders immediately. No configuration, no API keys, no login.
Related
What is claude-devtools?
A free, open-source debugging tool for Claude Code. Reads ~/.claude/ logs and reconstructs the full session — file paths, tool calls, thinking, tokens — that the terminal hides.
Install claude-devtools
Homebrew, direct download, or Docker. Works on macOS, Linux, and Windows. No API keys, no login, no configuration — claude-devtools just reads ~/.claude/.