Claude Code session log viewer for JSONL files in ~/.claude/projects. Browse conversations, tool calls, tokens, and live tail sessions on desktop, web, and TUI.
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 GUI app for macOS, Linux, and Windows, a Web app or a TUI.
Use Claude Code Trace when you want to:
View Claude Code conversation history from ~/.claude/projects/
The agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.
First-time install walkthrough for Claude Code, Codex CLI, and ChatGPT.
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.
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
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.
[!IMPORTANT]
macOS: The app is unsigned. After installing, remove the quarantine attribute:
xattr -cr /Applications/Claude\ Code\ Trace.app
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.
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.
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:
Note: The TUI is functional but has a few UX rough edges. Contributions are welcome.
MCP tool call support
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.
Keybindings
? toggles keybind hints in any view.
List 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 |
Detail view
| 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 |
Session picker
| Key | Action |
| ----------- | --------------------- |
| j / k | Navigate sessions |
| Enter | Open selected session |
| q / Esc | Back to list |
Debug log viewer
| Key | Action |
| ----------- | ------------ |
| q / Esc | Back to list |
Development
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
Check and test
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
Release
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](https://github.com/delexw/claude-code-
The agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.
Claude Code is an agentic coding tool that lives in your terminal, understands your codebase, and helps you code faster by executing routine tasks, explaining complex code, and handling git workflows - all through natural language commands.
