llms.txt
# claude-devtools
> claude-devtools is a free, open-source debugging tool for Claude Code. It reads the session logs already saved to `~/.claude/` on your machine and reconstructs everything Claude Code's terminal hides — exact file paths, tool call inputs and outputs, extended thinking, per-turn token attribution, subagent execution trees, and compaction events — in a structured, searchable interface. It does not wrap, modify, or proxy Claude Code; it is a read-only viewer for the JSONL transcripts Claude Code already writes to disk.
Since Claude Code v2.1.20, the terminal collapsed detailed output into opaque summaries (`Read 3 files`, `Edited 2 files`) with no file paths, no diffs, and no thinking content. The only built-in alternative is `--verbose`, which dumps raw JSON including internal system prompts. claude-devtools is the middle ground: structured access to the same data Claude Code already records, with zero configuration, no API keys, and no network calls.
Distribution: Electron app for macOS (Apple Silicon + Intel), Windows, Linux, plus a standalone Docker / Node.js server (`docker compose up`, port 3456). MIT license. Project repo: https://github.com/matt1398/claude-devtools.
## Documentation
- [Docs hub](https://claude-dev.tools/docs): Index of all guides and reference pages.
- [What is claude-devtools?](https://claude-dev.tools/docs/what-is): Overview, distribution, and what the tool does and doesn't do.
- [How to debug a Claude Code session](https://claude-dev.tools/docs/debugging): Practical entry point — what claude-devtools exposes that the terminal hides.
- [Install claude-devtools](https://claude-dev.tools/docs/installation): Homebrew, direct download, Docker.
- [Reading Claude Code session transcripts](https://claude-dev.tools/docs/transcripts): Chronological view, per-tool renderers, cross-session search, export.
- [How to debug Claude Code tool calls](https://claude-dev.tools/docs/tool-calls): Specialized viewers for Read, Edit, Bash, Grep, Task, Markdown, Mermaid.
- [How to view Claude Code token usage](https://claude-dev.tools/docs/token-usage): Per-turn token attribution across 7 categories.
- [Understanding Claude Code context compaction](https://claude-dev.tools/docs/compaction): Detect compaction boundaries, see token deltas, find what was lost.
- [Debugging subagents and teams](https://claude-dev.tools/docs/subagents): Per-agent execution trees, recursive nesting, color-coded teammate messages.
- [Setting up notification triggers](https://claude-dev.tools/docs/notifications): Built-in alerts plus custom regex triggers with per-repo scoping.
- [Inspecting remote sessions over SSH](https://claude-dev.tools/docs/ssh-remote): Read remote ~/.claude/ via SFTP with ~/.ssh/config aliases.
- [Where are Claude Code logs stored?](https://claude-dev.tools/docs/log-locations): Default ~/.claude/ paths on macOS, Linux, and Windows.
## Guides and reference
- [4 ways I cut Claude Code token usage](https://claude-dev.tools/docs/token-saving-lessons): Four token-drain patterns surfaced from watching real sessions — heavy MCPs, lazy @-mentions, probabilistic skills, and monolithic CLAUDE.md.
- [Why did Claude Code forget? Diagnosing compaction](https://claude-dev.tools/docs/why-claude-forgot): Walkthrough for finding and recovering from context compaction.
- [claude --verbose vs claude-devtools](https://claude-dev.tools/docs/verbose-vs-devtools): When to use each — live JSON stream vs. post-hoc structured viewer.
- [How to copy text from Claude Code](https://claude-dev.tools/docs/copy-paste): Copying terminal output mangles line wraps, ANSI codes, and Markdown — claude-devtools renders responses as real selectable text with one-click copy.
- [Anatomy of a Claude Code JSONL transcript](https://claude-dev.tools/docs/jsonl-format): Field-by-field reference for the on-disk session format.
## External
- [GitHub README](https://github.com/matt1398/claude-devtools/blob/main/README.md): Installation, problem statement, feature summary, Docker deployment.
- [Changelog](https://claude-dev.tools/changelog): Release history and version notes.
- [SECURITY.md](https://github.com/matt1398/claude-devtools/blob/main/SECURITY.md): Read-only architecture, IPC input validation, path containment, zero outbound network calls in standalone mode.
- [CONTRIBUTING.md](https://github.com/matt1398/claude-devtools/blob/main/CONTRIBUTING.md): Build from source (Node 20+, pnpm 10+), dev workflow, quality gates.
## Features
- Context reconstruction across 7 categories — CLAUDE.md (global/project/directory), skills, @-mentioned files, tool I/O, extended thinking, team overhead, user text.
- Compaction visualization with per-boundary token deltas.
- Tool call inspector with specialized viewers per tool (Read, Edit, Bash, Grep, Task, Markdown, Mermaid).
- Subagent and team debugging — recursive execution trees per agent with tool traces, tokens, duration, and cost.
- Notification triggers — built-in (.env access, tool errors, high token usage) plus custom regex on any field.
- SSH remote sessions over SFTP with ~/.ssh/config aliases, agent forwarding, and key auth.
- Command palette (Cmd+K) cross-session search and multi-pane drag-and-drop tabs.
- Live session updates — file watcher tails active sessions and appends new turns.
- Export — save rendered transcripts as Markdown, JSON, or plain text.
## Architecture
- Read-only access to `~/.claude/` (macOS: `/Users/<you>/.claude/`, Linux: `/home/<you>/.claude/`, Windows: `C:\Users\<you>\.claude\`).
- Session transcripts are JSONL files under `~/.claude/projects/<project>/`; each line is a user turn, assistant response, tool call, tool result, or system event.
- Electron build: main process for filesystem and SSH, preload bridge for IPC, renderer for UI. Standalone build: same renderer over a Node.js HTTP server.
- Not a wrapper: claude-devtools never invokes the Claude API, never modifies the Claude Code CLI, and never injects into Claude Code's process.
## Optional
- [Awesome Claude Code listing](https://github.com/hesreallyhim/awesome-claude-code): Community curation that includes claude-devtools.
- [Hacker News discussion on Claude Code v2.1.20 verbosity changes](https://news.ycombinator.com/item?id=46978710): Context for why claude-devtools exists.
