claude-devtools: reading Claude Code session logs in a desktop UI

What problem claude-devtools addresses

Claude Code writes session transcripts to ~/.claude/. The terminal shows a compressed version of those transcripts: "Read 3 files", "Searched for 1 pattern", "Edited 2 files". The README's framing is that since Claude Code v2.1.20 the CLI replaced detailed output with opaque summaries, and that the only remaining workaround is --verbose, which the README describes as dumping raw JSON, internal system prompts and thousands of lines of noise.

claude-devtools takes the position that the data is not missing, only unrendered. It reads the logs already on disk and reconstructs the parts the terminal drops: exact file paths with line numbers, the regex behind a search and the lines it matched, inline diffs for edits, extended thinking content, subagent execution trees, and a per-turn breakdown of what occupies the context window. It is aimed at developers debugging an agent that behaved unexpectedly, and at anyone trying to understand why a session burned tokens. It requires no API keys and no changes to how Claude Code is invoked, because it never sits between you and the model.

How the log reading actually works

The architecture is two processes. An Electron shell hosts the UI and a Node-side main process that reads transcripts from disk; the repository also builds a standalone HTTP server that serves the same renderer without Electron, which is what the Docker image runs. The build tooling is electron-vite, and the desktop bundles are produced by electron-builder for mac, win and linux targets, per the scripts in package.json.

The data flow starts at CLAUDE_ROOT. In the Dockerfile that variable defaults to /data/.claude, and docker-compose.yml mounts ${CLAUDE_DIR:-~/.claude} at /data/.claude read-only. The server parses the transcript files under that root and turns them into structured steps: tool calls with their inputs and outputs, thinking blocks, subagent invocations, and token accounting. The README describes context reconstruction as per-turn token attribution across seven categories, listing CLAUDE.md (global, project, directory), skills, @-mentioned files, tool I/O, thinking, team overhead and user text. That list is the app's model of a context window, and it is the most opinionated thing in the project: it asserts that a turn's tokens can be attributed to those buckets rather than shown as one number.

The standalone server is deliberately narrow. The Dockerfile externalizes fastify, @fastify/cors and @fastify/static from the bundle and installs them as production dependencies, so the HTTP path is a static renderer plus an API over the mounted directory. The compose file's comment states the standalone server makes zero outbound network calls, with no telemetry, analytics or auto-updater, and suggests network_mode: "none" for isolation. Treat that as a claim from the project's own configuration comments, not as an audited property.

Installing claude-devtools and opening a first session

On macOS the README gives a Homebrew cask as the shortest path. After it completes, the app appears in Applications like any other cask install.

brew install --cask claude-devtools

If you prefer a direct download, the releases page carries a .dmg for Apple Silicon (arm64) and Intel (x64), a .AppImage, .deb, .rpm or .pacman for Linux, and a .exe for Windows. The README notes two first-launch friction points: on macOS you right-click the app and choose Open, and on Windows the installer may trigger SmartScreen, where you click More info then Run anyway. Both are unsigned-build symptoms rather than configuration you can fix in the app.

The Docker route avoids installing anything on the host and is the one to use on a headless machine or a server. The compose file builds the image, publishes port 3456, and mounts your Claude directory read-only:

services:
  claude-devtools:
    build: .
    ports:
      - "3456:3456"
    volumes:
      - ${CLAUDE_DIR:-~/.claude}:/data/.claude:ro
    environment:
      - CLAUDE_ROOT=/data/.claude
      - HOST=0.0.0.0
      - PORT=3456

Run docker compose up from the repository root and open http://localhost:3456. The equivalent single command from the Dockerfile header is:

docker run -p 3456:3456 -v ~/.claude:/data/.claude:ro claude-devtools

For a first real use, pick a session you remember and open it. The README's comparison table is the checklist: a collapsed "Read 3 files" line should expand to exact paths with syntax-highlighted content and line numbers; "Edited 2 files" should become an inline diff with added and removed highlighting; the three-segment context bar should become a per-turn attribution across the seven categories. If an entry stays collapsed, that is your signal that the parser did not recognize that transcript shape.

Where claude-devtools stops being the right tool

It is a reader, not an interceptor. Everything it shows comes from transcripts that Claude Code has already written, so it cannot show you a turn that is still streaming, and it cannot warn you mid-session that the context window is filling up. If your problem is preventing a runaway agent rather than explaining one after the fact, this is the wrong category of tool.

The second constraint is the file system. The app needs to reach ~/.claude, or whatever CLAUDE_ROOT points at. The Docker setup mounts it read-only, which is the right default but also means the container sees only what the host exposes; point it at a directory that does not contain your real sessions and you get an empty UI with no obvious error. On a machine where Claude Code runs remotely, there is nothing local to read.

Third, the interface is a desktop app first. The standalone server exists and the Docker image is documented, but the README's primary installation story is Homebrew and signed-installer-style downloads, and the first-launch instructions assume a GUI. Anyone expecting a headless CLI that prints a session summary will not find one described.

Finally, the project's own history is worth weighing. The last push to the repository was on 2026-05-13, and the most recent release, v0.5.0, is dated the same day. Four months later that is not a stalled project, but it is also not a repository taking daily commits, and Claude Code's transcript format is owned by another team. A format change upstream is the failure mode to expect: sessions that open but render with missing steps.

How it differs from reading transcripts by hand or with a generic log viewer

The obvious alternative is the one the README names: run Claude Code with --verbose and read the JSON. That gives you the same underlying data with no third-party parser in between, and it is the honest choice if you only need to grep one session. The difference is rendering. --verbose emits internal system prompts and unfiltered records, and nothing in it is collapsed, filtered or attributed to a category. claude-devtools' value is the layer on top: chunking a transcript into steps, filtering noise, and assigning tokens to seven buckets so a turn's cost has a shape.

A second alternative is a general observability stack that instruments the agent through an SDK or proxy. That approach can capture live traces and aggregate across machines, which claude-devtools cannot, but it requires you to route Claude Code through the instrumented path. claude-devtools works retroactively on sessions you already ran, including old ones, which is a real advantage when the bug is in yesterday's run and you no longer have the terminal scrollback. The trade is coverage: an instrumented proxy sees every call, while a transcript parser sees only what the CLI chose to write down.

Licence, maintenance and upgrade cost

The project is MIT licensed, per both the LICENSE file and the license field in package.json. MIT is permissive: you can use, modify and redistribute it, including in commercial settings, provided the copyright notice and permission notice are preserved. That is a statement about the licence text, not legal advice; if you plan to redistribute a modified build, read the LICENSE file yourself.

The practical upgrade cost is low for the packaged app. Homebrew and the installers pull a new build, and there is no server-side component to migrate. The Docker path costs more, because the image is built from source: the Dockerfile runs pnpm install --frozen-lockfile, then pnpm standalone:build, then a second production-only install. Rebuilding after a pull means re-running the full multi-stage build, and upgrading Node means editing the node:20-slim base in two places. Pinning the image tag rather than rebuilding from main is the cheaper habit.

The maintenance question that matters more than commit frequency is format drift. Because the parser targets Claude Code's on-disk transcripts, an upstream change to that format shows up as parsing gaps rather than crashes. The repository carries a test/ directory with scripts such as test:chunks, test:semantic, test:noise and test:task-filtering, which suggests the parsing pipeline is covered by targeted tests; whether those tests track a new transcript format depends on someone updating the fixtures.

Editorial conclusion

Adopt claude-devtools if you already run Claude Code on macOS, Linux or Windows and want to read what a session actually did without parsing --verbose JSON by hand. Skip it if you need live monitoring of a running agent, if you cannot mount ~/.claude into the process, or if you want aggregate cost reporting across many machines; it reads local transcripts only. Before trusting it, run one session you remember well, open it in the app, and check that the file paths, diffs and token categories match what you saw in the terminal. Then confirm the Docker path exposes port 3456 only where you intend, because the container serves the UI over plain HTTP.

Frequently asked questions

Official sources

1. License: MIT
2. matt1398/claude-devtools on GitHub
3. Project website
4. README
5. Releases