claude-trace

Record all your interactions with Claude Code as you develop your projects. See everything Claude hides: system prompts, tool outputs, and raw API data in an intuitive web interface.

Fork changes

This is a fork of the upstream @mariozechner/claude-trace. It incorporates the following changes on top of upstream:

Native Bun binary support via reverse proxy (PR #56)

Modern Claude Code ships as a compiled native binary (Bun/ELF on Linux, Mach-O on macOS). The Node --require interceptor only works with JS-based Claude; for native binaries it is silently skipped. PR #56 added:

• Detection of native binaries via magic bytes (ELF / Mach-O / PE).
• A local HTTP reverse proxy that Claude's traffic is routed through, capturing requests and responses without needing to hook into the Node runtime.

Reverse proxy honors ANTHROPIC_BASE_URL

PR #56's reverse proxy was hard-coded to forward to api.anthropic.com. It now forwards to ANTHROPIC_BASE_URL instead (default https://api.anthropic.com), supporting http/https upstreams and base-path prefixes — so tracing through a relay or router just works:

ANTHROPIC_BASE_URL=https://your-relay.example.com ANTHROPIC_AUTH_TOKEN=sk-... \
  claude-trace --run-with -p "hello"

Install

npm install -g @mariozechner/claude-trace

Usage

# Start Claude Code with logging
claude-trace

# Include all API requests (by default, only substantial conversations are logged)
claude-trace --include-all-requests

# No-events mode: don't store raw SSE events, only the reconstructed messages (much smaller traces)
claude-trace --no-events

# Run Claude with specific arguments
claude-trace --run-with chat --model sonnet-3.5

# Show help
claude-trace --help

# Extract OAuth token
claude-trace --extract-token

# Generate HTML report manually from previously logged .jsonl
claude-trace --generate-html logs.jsonl report.html

# Generate HTML including all requests (not just substantial conversations)
claude-trace --generate-html logs.jsonl --include-all-requests

# Generate conversation summaries and searchable index
claude-trace --index

Logs are saved to .claude-trace/log-YYYY-MM-DD-HH-MM-SS.{jsonl,html} in your current directory. The HTML file is self-contained and opens in any browser without needing a server.

Request Filtering

By default, claude-trace filters logs to focus on substantial conversations:

• Default behavior: Only logs requests to /v1/messages with more than 2 messages in the conversation
• With --include-all-requests: Logs all requests made to the configured upstream endpoint (ANTHROPIC_BASE_URL, default api.anthropic.com — see Fork changes) including single-message requests and other endpoints

This filtering reduces log file size and focuses on meaningful development sessions, while still allowing you to capture everything when needed for debugging.

Event-free Traces

Streaming responses are logged as a long list of per-token SSE events (response.events / response.body_raw). For token-heavy sessions this is by far the largest part of the .jsonl and the embedded HTML data.

• --no-events: skips the raw SSE events and stores only the reconstructed final message (response.body). The conversation view renders identically; only the raw SSE list in the "Raw calls" debug view is omitted.

# Capture a session without raw SSE events
claude-trace --no-events

# Re-render an existing log into a smaller, event-free HTML
claude-trace --generate-html log.jsonl log.small.html --no-events

Note that --no-events affects what is captured/embedded going forward; it does not rewrite the raw events back into an already-recorded full .jsonl.

Conversation Indexing

Generate AI-powered summaries of your coding sessions:

claude-trace --index

This feature:

• Scans all .jsonl log files in .claude-trace/ directory
• Filters meaningful conversations (more than 2 messages, non-compacted)
• Uses Claude CLI to generate titles and summaries for each conversation
• Creates summary-YYYY-MM-DD-HH-MM-SS.json files with conversation metadata
• Generates a master index.html with chronological listing of all sessions
• Links directly to individual conversation HTML files

Note: Indexing will incur additional API token usage as it calls Claude to summarize conversations.

What you'll see

• System prompts - The hidden instructions Claude receives
• Tool definitions - Available tool descriptions and parameters
• Tool outputs - Raw data from file reads, searches, API calls
• Thinking blocks - Claude's internal reasoning process
• Token usage - Detailed breakdown including cache hits
• Raw JSONL logs - Complete request/response pairs for analysis
• Interactive HTML viewer - Browse conversations with model filtering
• Debug views - Raw calls shows all HTTP requests without filtering; JSON debug shows processed API data
• Conversation indexing - AI-generated summaries and searchable index of all sessions

Requirements

• Node.js 16+
• Claude Code CLI installed

Development

Running in dev mode

# Install dependencies
npm install

# Start dev mode
npm run dev

Dev mode compiles both the main app (src/) and frontend (frontend/src/) with file watching. For frontend development, open http://localhost:8080/test to see live updates as you modify frontend code.

Testing the CLI

# Test compiled version
node --no-deprecation dist/cli.js

# Test TypeScript source directly
npx tsx --no-deprecation src/cli.ts

Building

# Build everything
npm run build

# Or build specific parts
npm run build:backend  # CLI and interceptor
npm run build:frontend # Web interface

Generated artifacts:

• dist/ - Compiled CLI and interceptor JavaScript
• frontend/dist/ - Bundled web interface (CSS + JS)
• Built HTML generator that embeds the web interface

The built artifacts are ready for npm publishing and include:

• Self-contained HTML reports with embedded CSS/JS
• Node.js CLI with mitmproxy integration
• TypeScript definitions

Architecture

Two-part system:

1. Backend (src/)

   • CLI (cli.ts) - Command-line interface and argument parsing. Launches Claude Code and injects interceptors
   • Interceptor (interceptor.ts) - injects itself into Claude Code, intercepts calls to fetch(), and logs them to JSONL files in .claude-trace/ in the current working dir.
   • HTML Generator (html-generator.ts) - Embeds frontend into self-contained HTML reports
   • Index Generator (index-generator.ts) - Creates AI-powered conversation summaries and searchable index
   • Shared Conversation Processor (shared-conversation-processor.ts) - Core conversation processing logic shared between frontend and backend
   • Token Extractor (token-extractor.js) - A simpler interceptor that extracts Claude Code OAuth tokens

2. Frontend (frontend/src/)

   • app.ts - Main ClaudeApp component, handles data processing and view switching
   • index.ts - Application entry point, injects CSS and initializes app
   • types/claude-data.ts - TypeScript interfaces for API data structures
   • utils/data.ts - Processes raw HTTP pairs, reconstructs SSE messages
   • utils/markdown.ts - Markdown to HTML conversion utilities
   • components/simple-conversation-view.ts - Main conversation display with tool visualization
   • components/raw-pairs-view.ts - Raw HTTP traffic viewer
   • components/json-view.ts - JSON debug data viewer
   • styles.css - Tailwind CSS with VS Code theme variables