Claude Code Trace is a Claude Code session log viewer for local JSONL files stored in ~/.claude/projects/.

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. It also helps you find sessions by user message. It runs as a native desktop app for macOS, Linux, and Windows, or a web app.

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
• 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
• 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.

Grab the latest release from Releases:

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

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

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)

Docker is supported for web mode 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

Or with Docker Compose:

docker compose up --build

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

• Rust 1.77+
• 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 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 .dmg, .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

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.

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 build

npm run check            # run all checks at once
npx vitest run           # frontend tests
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 format

Push a version tag to trigger a GitHub Actions build:

git tag v0.4.0
git push origin v0.4.0

This 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.

MIT