Skip to content
BSWEN
Blog

What Is Claude DevTools and How Does It Work

Cowrie
Cowrie
Dev @ Bswen

I’ve been using Claude Code for a while now, and there’s one thing that always bugged me: I had no easy way to figure out what actually happened during a session. Claude Code logs everything to ~/.claude/, but those JSON files are raw and hard to make sense of.

Then I found Claude DevTools. It’s a read-only analysis tool that transforms those existing session log files into a searchable, visual interface. No API keys, no configuration—just install and point it at your logs.

The Problem: Flying Blind with Claude Code

When I first started using Claude Code, I noticed it was creating files in my home directory:

Terminal output
~/.claude/
├── projects/
│   └── abc123/
│       ├── sessions/
│       │   ├── 2026-03-20.jsonl
│       │   └── 2026-03-21.jsonl
│       └── logs/
└── settings.json

I tried opening one of these .jsonl files:

Raw session log (hard to read)
{"type":"user","content":"Fix the bug in auth.ts","timestamp":"2026-03-24T10:30:00Z"}
{"type":"assistant","content":"I'll read the file first...","timestamp":"2026-03-24T10:30:01Z"}
{"type":"tool_use","name":"Read","input":{"file_path":"/src/auth.ts"},"timestamp":"2026-03-24T10:30:02Z"}
{"type":"tool_result","content":"...file contents...","timestamp":"2026-03-24T10:30:03Z"}
{"type":"tool_use","name":"Edit","input":{"file_path":"/src/auth.ts","old_string":"...","new_string":"..."},"timestamp":"2026-03-24T10:30:05Z"}

The log was massive—thousands of lines of JSON with no easy way to:

  • Understand why Claude made certain decisions
  • Review tool usage patterns across sessions
  • Debug errors that happened during execution
  • See a high-level summary of what actually occurred

I tried using jq to parse the files, but it was tedious:

Attempting to parse logs manually
cat ~/.claude/projects/*/sessions/*.jsonl | jq 'select(.type=="tool_use") | .name' | sort | uniq -c

This gave me counts of tool calls, but no context. I needed something better.

What Claude DevTools Actually Does

Claude DevTools is NOT a wrapper or alternative client for Claude Code. It’s purely a log reader—it takes those existing .jsonl files that Claude Code already creates and presents them in a human-friendly way.

The setup is exactly zero-friction:

Installation
# Install via npm
npm install -g claude-devtools


# Run as Electron app (opens a GUI)
claude-devtools


# Or run with Docker
docker run -v ~/.claude:/root/.claude -p 3000:3000 claude-devtools


# Or run as a Node server
npx claude-devtools --server --port 3000

No API keys. No authentication. No config files. Just install and open.

When I first ran it, I pointed it at my ~/.claude/ directory and instantly saw:

  • All my historical sessions (every single one)
  • A searchable interface for finding specific conversations
  • Visual breakdowns of tool calls (Read, Edit, Bash, etc.)
  • Token usage statistics per session
  • Timeline view of what happened when

Why This Matters for Debugging

Let me show you a real scenario. I had a session where Claude Code was supposed to refactor a module, but the changes seemed wrong. Here’s how I used DevTools to figure out what happened:

  1. Open the session in DevTools - Found it by date
  2. Filter by “Edit” tool calls - See exactly what files were modified
  3. Read the assistant’s reasoning - Understand why it made those changes
  4. Check token usage - See if it hit context limits

What I discovered was that Claude had misread a file earlier in the session due to a truncated output, leading to incorrect assumptions. Without DevTools, I would have been guessing.

How the Tool Works Under the Hood

The architecture is straightforward:

Claude DevTools data flow
┌─────────────────────────────────────────────────────────┐
│                    ~/.claude/                           │
│  ┌─────────────────────────────────────────────────┐   │
│  │  sessions/*.jsonl (Claude Code creates these)   │   │
│  └─────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────┐
│              Claude DevTools (Read-Only)               │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐    │
│  │   Parser    │→ │  Indexer    │→ │    UI      │    │
│  │  (JSONL)    │  │  (SQLite)   │  │  (Electron) │    │
│  └─────────────┘  └─────────────┘  └─────────────┘    │
└─────────────────────────────────────────────────────────┘

The tool:

  1. Parses JSONL files into structured data
  2. Indexes them for fast searching (using SQLite internally)
  3. Presents through Electron GUI, Docker web interface, or Node server

Importantly, it never writes to your Claude Code data. It’s purely read-only analysis.

Common Misconceptions

When I first heard about Claude DevTools, I had some wrong assumptions:

Mistake 1: Thinking it’s a Claude wrapper

No—it doesn’t send prompts to Claude or wrap the API. It only reads log files that Claude Code already creates on your machine.

Mistake 2: Expecting real-time monitoring

DevTools reads completed session logs. It’s not watching your active Claude Code session in real-time. You analyze sessions after they’re done.

Mistake 3: Believing it needs configuration

I spent 10 minutes looking for a config file before realizing there isn’t one. You just point it at a directory and it works.

Practical Use Cases

Here’s how I actually use it day-to-day:

Debugging unexpected behavior:

When Claude Code does something I didn’t expect, I open the session in DevTools and trace back through the tool calls to find where things went wrong.

Learning prompt patterns:

I review successful sessions to see what prompts led to good outcomes, then refine my approach.

Audit trail for work:

For projects where I need to document what the AI did (code reviews, compliance), DevTools provides a clear record.

Token optimization:

By reviewing token usage patterns across sessions, I learned which types of tasks consume the most context—and adjusted my workflow accordingly.

Session Log Structure

For those curious about what Claude DevTools actually parses, here’s a simplified view of a session log entry:

Session log structure (simplified)
{
  "sessionId": "abc123",
  "timestamp": "2026-03-24T10:30:00Z",
  "messages": [
    {"role": "user", "content": "Refactor the auth module"},
    {"role": "assistant", "content": "I'll analyze the current structure..."}
  ],
  "toolCalls": [
    {"tool": "Read", "file": "src/auth.ts", "timestamp": "..."},
    {"tool": "Edit", "file": "src/auth.ts", "changes": "..."},
    {"tool": "Bash", "command": "npm test", "timestamp": "..."}
  ],
  "tokenUsage": {"input": 5000, "output": 2000}
}

DevTools transforms this raw structure into clickable, searchable, visual interfaces.

Running Options

You have three ways to run it:

Electron Desktop App (recommended for local use):

Run as desktop app
claude-devtools

Opens a native GUI. Works on macOS, Windows, and Linux.

Docker Container (for isolation):

Run in Docker
docker run -v ~/.claude:/root/.claude -p 3000:3000 claude-devtools

Keeps everything containerized. Useful if you don’t want to install Node dependencies.

Node Server (for remote access):

Run as web server
npx claude-devtools --server --port 3000

Access via browser. Useful if you want to share the interface across a team.

Summary

In this post, I explained what Claude DevTools is and how it solves the “black box” problem with Claude Code sessions. The tool reads existing log files from ~/.claude/ and presents them in a searchable, visual interface. Key points:

  • Zero setup required - no API keys, no config files
  • Read-only - it doesn’t modify your Claude Code data
  • Works with all sessions - every session you’ve ever run is accessible
  • Multiple interfaces - Electron app, Docker, or Node server
  • Practical for debugging - trace decisions, review patterns, audit work

If you use Claude Code regularly, DevTools is worth installing—it transforms raw session logs into actionable insights with almost no effort.

Final Words + More Resources

My intention with this article was to help others share my knowledge and experience. If you want to contact me, you can contact by email: Email me

Here are also the most important links from this article along with some further resources that will help you in this scope:

Oh, and if you found these resources useful, don’t forget to support me by starring the repo on GitHub!

Comments

Tags: