Claude Code Trace: a local viewer for ~/.claude/projects JSONL sessions

The JSONL files Claude Code leaves behind, and who ends up reading them

Claude Code writes session history to local JSONL files under ~/.claude/projects/. The README's own framing is that these files are useful for debugging and reviewing AI coding sessions but difficult to read directly. That is the problem Claude Code Trace targets, and it is a narrow one: the tool is a reader for a directory layout that another program owns.

The intended audience is people debugging their own Claude Code runs. The README lists the concrete jobs: viewing conversation history, finding a session by a user message, inspecting tool calls and MCP calls, watching token counts, and tailing a session while it is still running. A second audience appears in the README as well: people building local agent harnesses, with DovePaw Lite named as an example that Claude Code Trace is used to support. If you only want aggregate metrics across a fleet of machines, this is not that tool.

How it is put together: a Rust backend, a React frontend, and three front doors

The repository layout shows a Tauri v2 application: src-tauri/ holds the Rust side, src/ and shared/ hold the React frontend, tui-py/ holds a Python Textual terminal UI, and bin/ holds the cctrace launcher. The Dockerfile describes the runtime arrangement plainly. The Rust/axum backend runs headless behind a virtual X display, because Tauri v2's webview runtime on Linux links against webkit2gtk and needs a display even when no window is shown. The React frontend is built to a static bundle and served from the same axum process as an API fallback, so the whole app is reachable on a single port.

That single-process design explains why the three modes are not separate products. Desktop, web and TUI all talk to the same backend; the TUI is a Python client started alongside it. The data flow is one-directional for the core feature: session files are read from the projects directory, parsed, and rendered. The docker-compose file mounts the host's ~/.claude read-only with the comment that the app never needs to write there, which is a useful signal about scope. The one thing that is written is configuration: settings.json (projects dir, WSL distros, allowed CORS origins) lives under /home/app/.config, and the compose file adds a named volume for it precisely because it otherwise resets to {} on every container recreate.

Installing Claude Code Trace and opening a first session

The fastest path is a pre-built release: .dmg for macOS, .deb, .rpm or .AppImage for Linux, .msi or .exe for Windows. On macOS the app is unsigned, and the README's required step after installing is to strip the quarantine attribute:

xattr -cr /Applications/Claude\ Code\ Trace.app

If you prefer to build, the README gives a script that builds everything and puts the binary on your PATH. Requirements are Rust 1.77+, Node.js 18+, Xcode Command Line Tools on macOS, and on Linux the packages libwebkit2gtk-4.1-dev libayatana-appindicator3-dev librsvg2-dev libxdo-dev libssl-dev.

git clone git@github.com:delexw/claude-code-trace.git
cd claude-code-trace
./script/install.sh       # builds everything + installs to PATH

cctrace              # desktop app (default)
cctrace --web        # web mode (opens browser)
cctrace --tui        # terminal UI

After launching, the session picker appears and the README states that it automatically discovers Claude Code sessions from ~/.claude/projects/. Selecting a session shows the conversation; clicking a message expands its tool calls. In desktop mode, the toolbar has an Open in Browser action that opens http://localhost:1420 and hides the desktop window.

For a headless box, web mode runs in Docker and only web mode is supported there. The compose file maps host port 1421 to container port 1421 and mounts ~/.claude read-only:

docker build -t claude-code-trace .
docker run --rm -p 1421:1421 \
  -v "$HOME/.claude:/home/app/.claude:ro" \
  claude-code-trace
# then open http://localhost:1421

One detail worth copying rather than reinventing: the compose healthcheck calls /bin/bash explicitly, because the image's /bin/sh is dash and does not support the /dev/tcp redirect the check uses.

Where Claude Code Trace stops being the right tool

The README is explicit that this is not a general observability platform: it focuses on local Claude Code session logs and does not require sending traces to an external service. Read that as a boundary in both directions. There is no collector, no remote store, and no cross-machine view described. If two engineers each run Claude Code on their own laptops, nothing in the README suggests their sessions can be aggregated.

The web mode's exposure model deserves attention too. The Docker image defaults CCTRACE_HTTP_HOST to 0.0.0.0 and CCTRACE_HTTP_PORT to 1421, and settings.json includes allowed CORS origins, which tells you the HTTP surface is meant to be reachable from a browser rather than locked to loopback. The README does not document authentication for that endpoint. Anyone who publishes port 1421 beyond their own machine is exposing their session history, which contains prompts and tool output, on the strength of a mount flag that only makes the files read-only.

Two smaller gaps: the README does not document rollback or downgrade between releases, and it does not describe what happens when the projects directory contains a partially written JSONL file from a session that is still running. Live tailing is listed as a feature, so the tool clearly expects to read files mid-write, but the failure behaviour is not stated.

Claude Code Trace against hosted tracing stacks

The obvious comparison is a hosted LLM tracing product, and the search terms people use around this project suggest Langfuse and LangSmith are the ones they have in mind. The difference is architectural, not cosmetic. Hosted platforms assume you instrument the application so spans are emitted to a server, where they are stored, indexed, and shared across a team. Claude Code Trace assumes the opposite: the data already exists on disk because Claude Code wrote it, and the tool's job is to parse and display it. Nothing is emitted, nothing leaves the machine, and there is no query language.

That trade buys setup cost and privacy and costs you everything a backend provides. You cannot compare a session from last week against one from today with a query, you cannot alert on token spend, and you cannot hand a link to a colleague. The README's own comparison is against general observability platforms, and it positions the local-only design as the point rather than a limitation. For a single developer debugging their own runs, the local design wins on setup. For a team that needs shared history, it does not compete.

Maintenance, licence, and what upgrading actually involves

The last push to the repository was on 2026-09-14, and the most recent release listed is v0.15.0 from 2026-09-07, with v0.14.0 the day before and v0.13.0 on 2026-08-19. That cadence suggests the project is moving quickly, which cuts both ways for an adopter: fixes arrive, and so do changes. The README does not document a rollback path or a downgrade procedure, so pinning a release before upgrading is your own responsibility.

The licence is MIT, which is permissive and imposes no copyleft obligation on your own code. Note that the repository bundles several ecosystems with different licences of their own: the Rust backend, the React frontend, and the Python Textual TUI under tui-py/. If you vendor or redistribute the app, check the dependency licences rather than assuming MIT covers everything in the tree.

Upgrade cost in practice depends on how you installed it. A pre-built release is a download and replace, plus the xattr step again on macOS. A source install means re-running ./script/install.sh, which requires the Rust and Node toolchains to stay current. A Docker deployment means rebuilding the image; the compose file's named volume for /home/app/.config exists so your settings survive that rebuild.

Editorial conclusion

Adopt Claude Code Trace if you already run Claude Code locally and want to read its JSONL session history without opening the raw files, especially if you prefer a terminal UI or a browser tab over a signed desktop app. Skip it if you need hosted trace storage, multi-user access, or a signed macOS build with no post-install step. Before relying on it, verify that the app finds your sessions after launch, that the read-only mount or projects directory you configure is the one Claude Code actually writes to, and that the unsigned macOS build is acceptable for your machine, since the README's only remedy is running xattr -cr on the installed app.

Frequently asked questions

Official sources

1. delexw/claude-code-trace on GitHub
2. Issues
3. License: MIT
4. README
5. Releases