Skip to content

claude-trace.md

Latest commit

 

History

History
432 lines (328 loc) · 10.8 KB

claude-trace.md

File metadata and controls

432 lines (328 loc) · 10.8 KB
Raw
title claude-trace - Claude Code Debugging Tool
category tools
type debugging
status available
created 2025-10-25
tags
claude-code
debugging
mcp
trace
http-proxy
related
claude-code-docs-map
sentinel-mcp-capabilities
code_files
N/A (external tool)

claude-trace - Claude Code Debugging Tool

Purpose: HTTP proxy that intercepts and logs API traffic from Claude Code CLI, revealing internal agent behavior and tool usage patterns.

Source: Simon Willison's Blog

What It Does

claude-trace captures request/response pairs between Claude Code CLI and Anthropic API, including:

  • User prompts
  • Assistant responses
  • Tool invocations (MCP tools, file operations, bash commands)
  • Sub-agent dispatches (via dispatch_agent tool)
  • Detailed JSON payloads

Output:

  • .claude-trace/ folder with JSONL logs (structured data)
  • HTML interface for visual debugging (web UI)

Installation

Method 1: npx (Recommended - No Install)

npx @mariozechner/claude-trace --include-all-requests

Method 2: Global Install

npm install -g @mariozechner/claude-trace
claude-trace --include-all-requests

Requirements:

  • Node.js v20+ (✅ Available: v20.19.5)
  • Claude Code already installed and configured

How It Works

Technical Implementation:

  1. Monkey-patches global.fetch and Node.js HTTP library
  2. Injects interceptor via --require interceptor-loader.js
  3. Captures all HTTP traffic before encryption
  4. Logs to .claude-trace/{timestamp}.jsonl and .html

Visualization:

User → claude CLI → claude-trace proxy → Anthropic API
                         ↓
                  Log to JSONL + HTML

Usage Examples

Basic Trace Session

# Start trace proxy
npx @mariozechner/claude-trace --include-all-requests

# In another terminal, use Claude Code normally
claude
> Fix the bug in council.js

# Trace files appear in .claude-trace/
ls -lh .claude-trace/

View Traces in Browser

# Open HTML interface
open .claude-trace/trace-2025-10-25-21-30-00.html

# Or serve with Python
cd .claude-trace && python3 -m http.server 8080
# Visit http://localhost:8080

Filter Specific Events

# Only show tool invocations
cat .claude-trace/*.jsonl | jq 'select(.type == "tool_use")'

# Show sub-agent dispatches
cat .claude-trace/*.jsonl | jq 'select(.tool_name == "dispatch_agent")'

# Count API calls
wc -l .claude-trace/*.jsonl

Key Insights from Traces

Discovery: Sub-Agent Pattern

From Simon Willison's analysis:

"Claude Code uses a sub-agent pattern through a dispatch_agent tool, allowing multiple concurrent agents to perform searches and file operations autonomously."

Example from trace:

{
  "type": "tool_use",
  "tool_name": "dispatch_agent",
  "input": {
    "task": "Search for all references to TruthLens",
    "agent_type": "search"
  }
}

Visible in Traces:

  • Tool chains: Read → Grep → Edit → Bash sequences
  • Memory operations: vectorMemory.upsertDocs() calls
  • MCP server interactions: Supabase queries, Playwright actions
  • Token usage: Exact input/output token counts per request
  • Lens validation: TruthLens.apply() results with metrics

Integration with Soulfield OS

Use Cases

1. Debug Agent Orchestration

# Trace Soulfield agent execution
npx @mariozechner/claude-trace --include-all-requests

# In Claude Code
claude
> Use @marketing to create campaign plan

# Check trace for:
# - council.js routing logic
# - LensOrchestrator.apply() calls
# - memory-supabase.cjs upsertDocs
# - Auto-sync to Obsidian

2. Verify Lens Framework Integration

# Trace shows lens validation steps
cat .claude-trace/*.jsonl | jq 'select(.content | contains("TruthLens"))'

# Example output:
# {
#   "agent": "marketing",
#   "lens_results": {
#     "passed": true,
#     "metrics": {"cc": 0.8, "ud": 0.9, "icr": 0.1}
#   }
# }

3. Audit MCP Tool Usage

# See which MCP servers are being called
cat .claude-trace/*.jsonl | jq '.tool_name' | sort | uniq -c

# Output:
#   42 mcp__supabase__queryDatabase
#   18 mcp__playwright__playwright_navigate
#   12 mcp__perplexity__perplexity_search

4. Profile Token Usage

# Calculate total tokens used
cat .claude-trace/*.jsonl | jq '.usage.total_tokens' | paste -sd+ | bc

# Find expensive operations
cat .claude-trace/*.jsonl | jq 'select(.usage.total_tokens > 5000)'

Comparison: claude-trace vs Soulfield Logging

Feature claude-trace Soulfield Auto-Sync
Scope Claude Code CLI only Soulfield agents (:8790)
Capture Full HTTP traffic Agent interactions
Format JSONL + HTML JSONL + Obsidian MD
Real-time Yes (proxy) Yes (post-execution)
Tool visibility All MCP tools Agent-specific tools
Storage .claude-trace/ workspace/docs/Obsidian/daily/ + archive
Use case Debug Claude Code itself Track Soulfield agent work

Complementary Systems:

  • claude-trace → Debug Claude Code (Sentinel) behavior
  • Auto-Sync → Track Soulfield agent (@marketing, @finance) work

Known Limitations

1. HTTPS Only

  • Cannot decrypt TLS traffic (Claude Code → Anthropic API)
  • Relies on pre-encryption interception via fetch patching

2. Sub-Agent Traces

  • Sub-agents spawned with dispatch_agent create nested traces
  • HTML interface doesn't always show full sub-agent tree

3. Performance Overhead

  • Adds ~50-100ms latency per request (negligible for interactive use)
  • JSONL files grow quickly (10MB+ for long sessions)

4. No Soulfield Agent Tracing

  • Only captures Claude Code CLI traffic
  • Doesn't see Soulfield HTTP server (:8790) agent calls
  • Use backend/services/auto-obsidian-sync.cjs for agent tracing

Configuration Options

CLI Flags

# Include all requests (not just Claude API)
npx @mariozechner/claude-trace --include-all-requests

# Custom output directory
npx @mariozechner/claude-trace --output-dir ~/traces

# Disable HTML generation (JSONL only)
npx @mariozechner/claude-trace --no-html

# Verbose logging
npx @mariozechner/claude-trace --verbose

Environment Variables

# Disable trace (pass-through mode)
CLAUDE_TRACE_DISABLED=1 npx @mariozechner/claude-trace

# Custom log level
CLAUDE_TRACE_LOG_LEVEL=debug npx @mariozechner/claude-trace

Security Considerations

⚠️ IMPORTANT: Traces contain sensitive data

Captured in traces:

  • API keys (Anthropic, Supabase, Google Workspace)
  • User prompts (may include PII, credentials)
  • File contents (if read via Read tool)
  • Database query results (including private data)

Best Practices:

  1. Never commit .claude-trace/ to git (add to .gitignore)
  2. Redact traces before sharing 
    # Remove API keys from JSONL
cat trace.jsonl | jq 'del(.api_key)' > trace-redacted.jsonl
  3. Delete traces after debugging 
    rm -rf .claude-trace/
  4. Use read-only MCP keys during trace sessions (limit damage if leaked)

Troubleshooting

Issue: "claude-trace not found"

Solution: Use npx (no install needed)

npx @mariozechner/claude-trace --include-all-requests

Issue: "No traces appearing in .claude-trace/"

Causes:

  • Claude Code not running during trace
  • --include-all-requests flag missing
  • Permissions issue (can't write to current directory)

Solution:

# Check directory permissions
ls -ld .claude-trace/

# Run with verbose logging
npx @mariozechner/claude-trace --include-all-requests --verbose

Issue: "HTML interface shows empty traces"

Cause: Traces contain sub-agent dispatches (nested structure)

Solution:

  • Expand collapsed sections in HTML UI
  • Or parse JSONL directly: 
    cat .claude-trace/*.jsonl | jq -r '.content | select(. != null)'

Related Tools

Similar Debugging Tools:

  • MCP Inspector - Inspect MCP server traffic (built-in to Claude Code)
  • Anthropic API Console - View API logs on Anthropic dashboard
  • chrome://tracing - Chrome DevTools tracing (for web UI)

Soulfield Equivalents:

  • auto-obsidian-sync.cjs - Logs agent interactions to Obsidian
  • backend/scripts/audit-truth.cjs - Audit TruthLens compliance
  • rollup-service.cjs - Aggregate daily logs into weekly summaries

Examples from Production

Example 1: Debug Memory Upsert Failure

# Start trace
npx @mariozechner/claude-trace --include-all-requests

# Use Claude Code
claude
> Check why @seo isn't remembering Leeds campaigns

# View trace
cat .claude-trace/*.jsonl | jq 'select(.tool_name == "mcp__supabase__queryDatabase")'

# Output shows:
# - Query: SELECT * FROM agent_memories WHERE agent = 'seo'
# - Result: 0 rows (agent name mismatch: 'seo' vs '@seo')
# - Root cause: council.js:2056 strips @ prefix

Example 2: Profile Token Usage for Cost Optimization

# Trace full session
npx @mariozechner/claude-trace --include-all-requests

# Run expensive operation
claude
> Analyze all 48 reference files and create summary

# Calculate cost
cat .claude-trace/*.jsonl | jq -r '[.usage.total_tokens] | add'
# Output: 127,000 tokens = $1.52 (at $0.012/1K tokens)

# Optimize: Use sub-agents to split work
# Re-run with optimization
# New cost: 34,000 tokens = $0.41 (73% savings)

Example 3: Verify Lens Pipeline Execution

# Trace lens validation
npx @mariozechner/claude-trace --include-all-requests

# Test @marketing with full lens pipeline
claude
> @marketing Create campaign for Leeds plumber

# Check trace for lens sequence
cat .claude-trace/*.jsonl | jq '.lens_results.sequence'

# Output: ["truth", "causality", "contradiction", "extrapolation", "rights", "structure"]
# ✅ Confirms full 6-lens pipeline executed

Quick Reference

Command Purpose
npx @mariozechner/claude-trace --include-all-requests Start trace proxy
ls -lh .claude-trace/ View trace files
open .claude-trace/*.html Open HTML interface
cat .claude-trace/*.jsonl | jq '.' Parse JSONL logs
rm -rf .claude-trace/ Clean up traces

Next Steps

To use claude-trace with Soulfield:

  1. Add .claude-trace/ to .gitignore
  2. Run trace during development sessions
  3. Use traces to debug lens validation failures
  4. Profile token usage for cost optimization
  5. Delete traces after each session (security)

See Also:

  • [[claude-code-docs-map]] - Claude Code documentation index
  • [[sentinel-mcp-capabilities]] - MCP tools available to Sentinel
  • [[auto-obsidian-sync]] - Soulfield agent logging (complementary)

Last Updated: 2025-10-25 Status: Available via npx (no install required) Security: ⚠️ Contains sensitive data - never commit traces to git