claude-code-trace

Claude Code Trace

Claude Code Trace is a Claude Code session log viewer and Jev-powered AI agent efficiency analyzer for local JSONL files stored in ~/.claude/projects/. It combines real-time Claude Code trace observability with structured behavioural analysis from Jev, TypeSafe AI's System One Model.

Browse, tail, and inspect Claude Code conversations in real time. Claude Code Trace renders Claude Code JSONL session files as readable conversations with expandable tool calls, token counts, timestamps, MCP tool call detection, and live log tailing. Its optional Jev integration scores agent progress, tool use, focus, exploration, recovery, and token efficiency using typed probabilistic decisions. It runs as a GUI app for macOS, Linux, and Windows, a Web app or a TUI.

Jev-powered AI agent efficiency analysis

Claude Code Trace turns a Claude Code agent trace into a privacy-reviewed, redacted analysis request for Jev. The resulting session efficiency dashboard helps identify repeated work, thrashing, excessive exploration, failed retries, effective recovery, useful subagent work, and inefficient token usage.

• Structured Jev decisions — evaluates agent behaviour using typed probabilities rather than generated prose
• Token efficiency analysis — considers total tokens, context growth, turns, repeated work, and tool activity without evaluating monetary cost
• Trace-linked findings — jumps from an efficiency finding to the relevant Claude Code messages
• Privacy before external analysis — shows the exact redacted payload and requires confirmation before sending it
• Secure API tokens — stores Jev and provider API tokens in macOS Keychain, Windows Credential Manager, or Linux Secret Service
• Versioned local results — caches one latest result per session and marks it stale when the trace or analysis formula changes

Integration credit: The Jev-powered Claude Code analysis workflow was designed and built in Claude Code Trace by delexw. Jev is developed by TypeSafe AI; this open-source project is independent and is not an official TypeSafe AI integration.

Use Claude Code Trace when you want to:

• View Claude Code conversation history from ~/.claude/projects/
• Find Claude Code sessions by user message
• Inspect Claude Code tool calls, MCP calls, timestamps, and token usage
• Analyze Claude Code agent efficiency with Jev and review trace-linked behavioural findings
• Monitor live Claude Code sessions while they are running
• Debug long-running Claude Code workflows without reading raw JSONL files
• Support and build a personal AI harness platform such as DovePaw Lite
• Browse Claude Code session logs from a desktop, browser, or terminal interface

Claude Code Trace is also used to support and build DovePaw Lite, a personal AI harness platform for orchestrating local agents.

Also check out Codex Trace — a session viewer for OpenAI Codex.

Features

• Claude Code JSONL viewer — reads local Claude Code session files from ~/.claude/projects/
• Conversation browser — renders raw JSONL logs as scrollable Claude Code conversations
• Live tailing — monitor active Claude Code sessions in real time
• Session search — find sessions by user message
• Tool call inspection — expand Claude Code tool calls for detailed debugging
• MCP support — detects Model Context Protocol tool calls and displays human-friendly names
• Token visibility — shows token counts where available in Claude Code session data
• Jev-powered efficiency analysis — scores progress, tool use, focus, exploration, recovery, and token efficiency with trace-linked findings
• Desktop, web, and TUI modes — choose the interface that fits your workflow
• Cross-platform builds — supports macOS, Linux, and Windows

Why use Claude Code Trace?

Claude Code stores local session history as JSONL files. Those files are useful for debugging and reviewing AI coding sessions, but they are difficult to read directly. Claude Code Trace turns those JSONL logs into an interactive session viewer so you can find sessions by user message, inspect conversations, understand tool usage, and debug Claude Code workflows faster.

Unlike general observability platforms, Claude Code Trace focuses on local Claude Code session logs. It does not require sending traces to an external service.

Claude Code Trace is especially useful when building personal AI harnesses and local agent platforms. It helps inspect Claude Code sessions, understand tool usage, and debug the workflows that power projects like DovePaw Lite.

Install

macOS — one-line install

[!TIP] No clone. No build tools. No xattr. Paste this into your terminal:

curl -fsSL https://raw.githubusercontent.com/delexw/claude-code-trace/main/script/install-macos.sh | bash

This downloads the latest release and installs Claude Code Trace.app into /Applications, ready to open from Spotlight.

macOS blocks unsigned apps that were flagged as downloaded, and curl never sets that flag — so the app just opens, with no quarantine workaround. That is why macOS releases ship a .app.tar.gz and no .dmg. Apple Silicon only.

Pin a specific version, or install somewhere else, with:

curl -fsSL https://raw.githubusercontent.com/delexw/claude-code-trace/main/script/install-macos.sh \
  | CCTRACE_VERSION=v0.15.1 CCTRACE_INSTALL_DIR=~/Applications bash

Download pre-built app — Linux and Windows

Grab the latest release from Releases:

On macOS, use the one-line install above. Downloading the macOS build by hand is not supported — the app is unsigned, so anything a browser downloads is quarantined and refuses to open until you clear the flag yourself.

Build from source

Use this option if you want to build Claude Code Trace locally on macOS, Linux, or Windows with Rust and Node.js installed.

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

Run from source without installing

git clone git@github.com:delexw/claude-code-trace.git
cd claude-code-trace
npm install

npm run tauri dev        # desktop app with hot reload
npm run dev:web          # web mode (opens browser)
npm run dev:tui          # TUI (starts backend + terminal UI)

Run in Docker

Docker is supported for web mode only.

For an interactive deployment, use the redeploy script. It asks whether you want to configure or update the Jev API key, reads it without echoing, and stores it in a Docker-managed volume that is mounted read-only by the running container:

./script/redeploy.sh

Answer No to keep the existing Docker key unchanged or to run without Jev analysis.

For a manual deployment without the interactive prompt:

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

Or use Docker Compose directly:

docker compose up --build

See docs/docker.md for runtime environment variables, volume layout, and troubleshooting.

Requirements

• Rust 1.88+
• Node.js 18+
• macOS: Xcode Command Line Tools (xcode-select --install)
• Linux: libwebkit2gtk-4.1-dev libayatana-appindicator3-dev librsvg2-dev libxdo-dev libssl-dev
• Windows: WebView2 is required and is pre-installed on Windows 10 and Windows 11

Usage

cctrace              # desktop app (default)
cctrace --web        # web mode (opens browser at http://localhost:1420)
cctrace --tui        # terminal UI (starts backend + TUI together)

Launch Claude Code Trace to open the session picker. It automatically discovers Claude Code sessions from ~/.claude/projects/.

Select a session to view the conversation. Click messages to expand tool calls, or open the detail view for full inspection.

Analyze a Claude Code session with Jev

1. In the desktop app, open Settings → Analytics and save your Jev API key to the operating system credential store. In web mode, provide JEV_API_KEY in the server environment; the HTTP API deliberately does not accept API-token save or clear requests. The TUI is an HTTP client too, so it reads the key the same way web mode does and cannot store one.
2. Select Analyse efficiency on a session. In the TUI, press a on a session row; , opens the same analytics settings.
3. Review the locally redacted payload and explicitly confirm before it is sent.
4. Use the efficiency dashboard and trace annotations to inspect Jev's findings. The TUI shows live analysis progress and the score on the session row; the dashboard itself is desktop and web only.

The default minimized mode sends extracted behavioural signals and selected excerpts. Full-transcript mode is available when more context is needed. Re-analysis replaces the previous result for that session, and API tokens are never written to the settings file.

In desktop mode, click Open in Browser in the toolbar to switch to browser mode. This opens http://localhost:1420 in your default browser and hides the desktop window.

If you installed the pre-built .app, .deb, or .msi, you can also launch the desktop app directly and pass --web to the binary:

# macOS
/Applications/Claude\ Code\ Trace.app/Contents/MacOS/claude-code-trace --web

API access

The local HTTP API (port 11423) only answers accepted clients: every caller presents its own signed credential, so the backend knows who is asking and any one client can be revoked without affecting the rest. The web UI and the TUI are registered automatically (web-ui, tui); the desktop app talks over IPC and needs nothing. Settings → Accepted clients lists them and lets you