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.
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.
- 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
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.
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 | bashThis 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 bashGrab the latest release from Releases:
| Platform | File |
|---|---|
| Linux | .deb, .rpm, .AppImage |
| Windows | .msi, .exe |
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.
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 UIgit 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)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.shAnswer 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:1421Or use Docker Compose directly:
docker compose up --buildSee docs/docker.md for runtime environment variables, volume layout, and troubleshooting.
- 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
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.
- 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_KEYin 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. - Select Analyse efficiency on a session. In the TUI, press
aon a session row;,opens the same analytics settings. - Review the locally redacted payload and explicitly confirm before it is sent.
- 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 --webThe 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
add, reissue or revoke clients. For your own scripts, add a client there and copy its credential
(shown once), or bootstrap from the TUI's file in the config dir (~/.config/claude-code-trace;
macOS: ~/Library/Application Support/claude-code-trace, Windows: %APPDATA%\claude-code-trace):
curl -H "X-CCTrace-Token: $(cat ~/.config/claude-code-trace/clients/tui.jwt)" \
http://127.0.0.1:11423/api/whoamiSet CCTRACE_API_AUTH=off to disable the check.
Note: The TUI is functional but has a few UX rough edges. Contributions are welcome.
MCP (Model Context Protocol) tool calls are automatically detected and displayed with human-friendly names.
For example, mcp__chrome-devtools__take_screenshot renders as MCP chrome-devtools with the summary take screenshot.
Supported MCP servers include chrome-devtools, figma, atlassian, buildkite, cloudflare, and any other server following the mcp__<server>__<tool> naming convention.
? toggles keybind hints in any view.
| Key | Action |
|---|---|
j / k |
Move cursor down / up |
G / g |
Jump to last / first message |
Tab |
Toggle expand/collapse current message |
e / c |
Expand / collapse all Claude messages |
Enter |
Open detail view |
d |
Open debug log viewer |
t |
Open team task board when teams exist |
s / q / Esc |
Open session picker |
| Key | Action |
|---|---|
j / k |
Navigate items |
Tab |
Toggle expand/collapse item |
Enter |
Open subagent or toggle expand |
h / l |
Switch panels left / right |
q / Esc |
Back to list |
| Key | Action |
|---|---|
j / k |
Navigate sessions |
Enter |
Open selected session |
q / Esc |
Back to list |
| Key | Action |
|---|---|
q / Esc |
Back to list |
npm install
npm run tauri dev # desktop app with hot reload
npm run dev:web # web mode, no desktop window
npm run dev:tui # TUI, starts backend + terminal UI together
npm run tauri build # production buildnpm run check # run all checks at once
npx vitest run # frontend tests
npm run test:e2e # Playwright end-to-end (builds the headless backend + web UI, drives Chromium)
cargo test --manifest-path src-tauri/Cargo.toml # Rust tests
npx tsc --noEmit # TypeScript type check
npx oxlint # JS/TS lint
npx oxfmt # JS/TS format
cargo clippy --manifest-path src-tauri/Cargo.toml # Rust lint
cargo fmt --manifest-path src-tauri/Cargo.toml # Rust formatPush a version tag to trigger a GitHub Actions build:
git tag v0.4.0
git push origin v0.4.0This creates a draft release with macOS, Linux, and Windows artifacts attached. Review and publish it from the Releases page.
Bug reports, feature requests, and pull requests are welcome. See Development for how to build and run locally. For significant changes, open an issue first to align on scope.