Claude Code Debugging Docs
The complete guide to debugging Claude Code sessions. Read session transcripts, inspect Claude Code logs, track token usage, and see everything the terminal hides.
Start here
What is claude-devtools?
A free, open-source Claude Code debugger that reads ~/.claude/ logs and reconstructs full session transcripts.
How to debug a Claude Code session
Restore the detail Claude Code's terminal collapsed. The middle ground between summaries and --verbose.
Installation
Homebrew, direct download, and Docker. macOS, Linux, Windows. No API keys, no login, no setup.
Features
Reading session transcripts
Chronological conversation view, per-tool renderers, cross-session search, export to Markdown / JSON / text.
Debugging tool calls
Syntax-highlighted Read, inline Edit diffs, full Bash output, regex search matches, recursive subagent trees.
Viewing token usage
Per-turn token attribution across 7 categories. Replace Claude Code's opaque progress bar with actual numbers.
Context window compaction
See the moment context fills, compresses, and refills. Inspect what was discarded across the boundary.
Subagents and teams
Each subagent renders as its own execution tree with tool traces, tokens, duration, and cost. Recursive nesting.
Notification triggers
Built-in alerts for .env access, tool errors, high token usage. Custom regex on any field with per-repo scope.
Remote sessions over SSH
Inspect Claude Code sessions on remote machines via SFTP. ~/.ssh/config aliases, agent forwarding, key auth.
Where are Claude Code logs stored?
Default ~/.claude/ paths on macOS, Linux, and Windows. Where session transcripts, projects, and config live.
Guides & reference
Why did Claude Code forget? Diagnosing compaction
Step-by-step walkthrough: find the compaction boundary, see what was lost, re-prime the new context, prevent next time.
claude --verbose vs claude-devtools
Both surface the data Claude Code's terminal hides. When to use each — live stream vs. post-hoc structured viewer.
Anatomy of a Claude Code JSONL transcript
Field-by-field reference for the JSONL session format. Read or process transcripts directly with jq, Python, anything.
Frequently asked questions
What is the best Claude Code debugging tool?+
claude-devtools is a free, open-source debugging tool for Claude Code. It reads Claude Code logs from ~/.claude/ and reconstructs full session transcripts — every file path, tool call, thinking step, and token — in a structured, searchable interface. It does not wrap or modify Claude Code.
Where are Claude Code logs and session transcripts stored?+
Claude Code saves session transcripts as JSONL logs to ~/.claude/ on your machine. On macOS: /Users/<you>/.claude/, on Linux: /home/<you>/.claude/, on Windows: C:\Users\<you>\.claude\. These logs exist whether or not you use claude-devtools.
How do I debug a Claude Code session?+
Open claude-devtools and select the session from the sidebar. You'll see the full session transcript with every tool call expanded, thinking steps visible, token usage broken down per turn, and subagent execution rendered as a tree. It is the alternative to --verbose that developers have been asking for.
How do I read Claude Code session transcripts?+
Claude Code transcripts are stored as JSONL files in ~/.claude/projects/. Raw transcripts are unreadable (escaped JSON with system prompts). claude-devtools parses them and renders a chronological conversation view with specialized renderers for each tool and cross-session search.
How do I see Claude Code token usage?+
claude-devtools provides per-turn token attribution across 7 categories: CLAUDE.md files, skill activations, @-mentioned files, tool call I/O, extended thinking, team overhead, and user text. This replaces the terminal's three-segment progress bar with actual numbers.
Does claude-devtools modify Claude Code?+
No. claude-devtools is read-only. It reads the session logs that already exist on your machine and has zero interaction with Claude Code itself. It works with every session you've ever run.
What platforms does claude-devtools support?+
macOS (Apple Silicon and Intel), Windows, Linux, and Docker. Install via Homebrew (brew install --cask claude-devtools) or download directly from GitHub releases.