Debugging Claude Code with Browser DevTools

This guide provides comprehensive techniques for debugging Claude Code sessions using browser developer tools, with a focus on network inspection, API call monitoring, and troubleshooting common issues.

Overview

When developing with Claude Code, understanding how to debug API interactions, monitor network requests, and troubleshoot issues is crucial for:

• Diagnosing API timeout errors
• Monitoring token usage and costs
• Debugging streaming responses
• Analyzing request/response patterns
• Identifying performance bottlenecks

Chrome DevTools Integration

Chrome DevTools MCP Server

The Chrome DevTools MCP (Model Context Protocol) server enables seamless integration between Claude Code and Chrome’s debugging capabilities:

// claude_desktop_config.json
{
  "mcpServers": {
    "chrome-devtools": {
      "command": "node",
      "args": ["/path/to/chrome-devtools-mcp/index.js"],
      "env": {
        "CDP_PORT": "9222"
      }
    }
  }
}

Key features:

• Network Monitoring: Capture and analyze HTTP requests/responses
• Console Integration: Read browser console logs and execute JavaScript
• Performance Analysis: Access timing data and resource loading
• Real-time Monitoring: Inspect web elements and network traffic
• Object Inspection: Deep dive into JavaScript objects and variables

Network Inspection Techniques

1. Monitoring Claude API Calls

Open Chrome DevTools Network panel to monitor Claude Code API interactions:

// Example: Intercepting Claude API requests
const originalFetch = window.fetch;
window.fetch = async function(...args) {
  const [url, options] = args;
  
  // Log Claude API calls
  if (url.includes('api.anthropic.com')) {
    console.log('Claude API Request:', {
      url,
      method: options?.method,
      headers: options?.headers,
      body: options?.body
    });
  }
  
  const response = await originalFetch.apply(this, args);
  
  // Log response details
  if (url.includes('api.anthropic.com')) {
    const clonedResponse = response.clone();
    const responseData = await clonedResponse.json();
    console.log('Claude API Response:', {
      status: response.status,
      headers: Object.fromEntries(response.headers),
      data: responseData
    });
  }
  
  return response;
};

2. Request/Response Analysis

Key areas to inspect in the Network panel:

Headers Tab:

• x-api-key: Verify API key is properly set
• anthropic-version: Check API version
• content-type: Should be application/json
• Rate limit headers: x-ratelimit-limit, x-ratelimit-remaining

Payload Tab:

{
  "model": "claude-3-sonnet-20240229",
  "messages": [{
    "role": "user",
    "content": "Your prompt here"
  }],
  "max_tokens": 4096,
  "stream": true
}

Response Tab:

• Monitor streaming chunks for SSE (Server-Sent Events)
• Check for error messages and status codes
• Verify response format and content

3. Timing Analysis

Use the Timing tab to identify performance bottlenecks:

// Performance monitoring wrapper
class ClaudePerformanceMonitor {
  constructor() {
    this.metrics = [];
  }
  
  async measureApiCall(prompt, options = {}) {
    const startTime = performance.now();
    const marks = {
      start: startTime,
      firstByte: null,
      lastByte: null,
      complete: null
    };
    
    try {
      const response = await fetch('https://api.anthropic.com/v1/messages', {
        method: 'POST',
        headers: {
          'content-type': 'application/json',
          'x-api-key': process.env.ANTHROPIC_API_KEY,
          'anthropic-version': '2023-06-01'
        },
        body: JSON.stringify({
          model: 'claude-3-sonnet-20240229',
          messages: [{ role: 'user', content: prompt }],
          ...options
        })
      });
      
      marks.firstByte = performance.now();
      
      const data = await response.json();
      marks.lastByte = performance.now();
      marks.complete = performance.now();
      
      this.metrics.push({
        prompt: prompt.substring(0, 50) + '...',
        duration: marks.complete - marks.start,
        timeToFirstByte: marks.firstByte - marks.start,
        downloadTime: marks.lastByte - marks.firstByte,
        timestamp: new Date().toISOString()
      });
      
      return data;
    } catch (error) {
      console.error('API call failed:', error);
      throw error;
    }
  }
  
  getMetrics() {
    return {
      calls: this.metrics.length,
      avgDuration: this.metrics.reduce((sum, m) => sum + m.duration, 0) / this.metrics.length,
      avgTTFB: this.metrics.reduce((sum, m) => sum + m.timeToFirstByte, 0) / this.metrics.length,
      metrics: this.metrics
    };
  }
}

Common Issues and Solutions

1. API Timeout Errors

Problem: Claude Code API requests timing out Solution: Implement proper retry logic with exponential backoff

// Retry configuration for Claude API calls
const RETRY_CONFIG = {
  maxRetries: 3,
  initialDelay: 1000,
  maxDelay: 10000,
  backoffMultiplier: 2,
  timeout: 60000 // 60 seconds
};
 
async function callClaudeWithRetry(prompt: string, options = {}) {
  let lastError;
  
  for (let attempt = 0; attempt < RETRY_CONFIG.maxRetries; attempt++) {
    try {
      const controller = new AbortController();
      const timeoutId = setTimeout(
        () => controller.abort(),
        RETRY_CONFIG.timeout
      );
      
      const response = await fetch('https://api.anthropic.com/v1/messages', {
        ...options,
        signal: controller.signal,
        body: JSON.stringify({
          model: 'claude-3-sonnet-20240229',
          messages: [{ role: 'user', content: prompt }],
          ...options.body
        })
      });
      
      clearTimeout(timeoutId);
      
      if (!response.ok) {
        throw new Error(`API error: ${response.status} ${response.statusText}`);
      }
      
      return await response.json();
    } catch (error) {
      lastError = error;
      console.error(`Attempt ${attempt + 1} failed:`, error);
      
      if (attempt < RETRY_CONFIG.maxRetries - 1) {
        const delay = Math.min(
          RETRY_CONFIG.initialDelay * Math.pow(RETRY_CONFIG.backoffMultiplier, attempt),
          RETRY_CONFIG.maxDelay
        );
        await new Promise(resolve => setTimeout(resolve, delay));
      }
    }
  }
  
  throw lastError;
}

2. CORS Issues

Problem: Cross-Origin Resource Sharing errors when calling Claude API from browser Solution: Use a proxy server or backend endpoint

// Backend proxy endpoint (Node.js/Express)
app.post('/api/claude-proxy', async (req, res) => {
  try {
    const response = await fetch('https://api.anthropic.com/v1/messages', {
      method: 'POST',
      headers: {
        'content-type': 'application/json',
        'x-api-key': process.env.ANTHROPIC_API_KEY,
        'anthropic-version': '2023-06-01'
      },
      body: JSON.stringify(req.body)
    });
    
    const data = await response.json();
    res.json(data);
  } catch (error) {
    console.error('Proxy error:', error);
    res.status(500).json({ error: 'Proxy request failed' });
  }
});

3. Streaming Response Debugging

Problem: Difficulty debugging Server-Sent Events (SSE) streams Solution: Create a stream debugger

class StreamDebugger {
  private chunks: any[] = [];
  private startTime: number;
  
  async debugStream(response: Response) {
    this.startTime = Date.now();
    const reader = response.body?.getReader();
    const decoder = new TextDecoder();
    
    if (!reader) throw new Error('No response body');
    
    try {
      while (true) {
        const { done, value } = await reader.read();
        
        if (done) break;
        
        const chunk = decoder.decode(value, { stream: true });
        const timestamp = Date.now() - this.startTime;
        
        this.chunks.push({
          timestamp,
          size: value.byteLength,
          content: chunk,
          parsed: this.parseSSE(chunk)
        });
        
        // Log in DevTools console
        console.log(`[${timestamp}ms] Chunk received:`, {
          size: value.byteLength,
          preview: chunk.substring(0, 100)
        });
      }
    } finally {
      reader.releaseLock();
    }
    
    return this.analyze();
  }
  
  private parseSSE(chunk: string): any[] {
    const events = [];
    const lines = chunk.split('\n');
    
    for (const line of lines) {
      if (line.startsWith('data: ')) {
        try {
          const data = JSON.parse(line.slice(6));
          events.push(data);
        } catch (e) {
          // Not JSON, raw text
          events.push({ raw: line.slice(6) });
        }
      }
    }
    
    return events;
  }
  
  analyze() {
    return {
      totalChunks: this.chunks.length,
      totalDuration: Date.now() - this.startTime,
      totalBytes: this.chunks.reduce((sum, c) => sum + c.size, 0),
      avgChunkSize: this.chunks.reduce((sum, c) => sum + c.size, 0) / this.chunks.length,
      chunks: this.chunks
    };
  }
}

Advanced Debugging Techniques

1. Request Interception and Modification

// Using Chrome DevTools Protocol
const CDP = require('chrome-remote-interface');
 
async function interceptClaudeRequests() {
  const client = await CDP();
  const { Network, Fetch } = client;
  
  await Network.enable();
  await Fetch.enable({
    patterns: [{
      urlPattern: '*api.anthropic.com*',
      requestStage: 'Request'
    }]
  });
  
  Fetch.requestPaused(async ({ requestId, request }) => {
    console.log('Intercepted Claude request:', request);
    
    // Modify headers
    const headers = Object.entries(request.headers).map(([name, value]) => ({
      name,
      value: name === 'x-custom-header' ? 'modified-value' : value
    }));
    
    // Continue with modified request
    await Fetch.continueRequest({
      requestId,
      headers
    });
  });
}

2. Performance Profiling

// Profile Claude Code operations
class ClaudeProfiler {
  constructor() {
    this.profiles = new Map();
  }
  
  startProfile(name: string) {
    this.profiles.set(name, {
      name,
      startTime: performance.now(),
      marks: [],
      measures: []
    });
    
    performance.mark(`${name}-start`);
  }
  
  mark(profileName: string, markName: string) {
    const profile = this.profiles.get(profileName);
    if (!profile) return;
    
    const markId = `${profileName}-${markName}`;
    performance.mark(markId);
    profile.marks.push({ name: markName, id: markId });
  }
  
  endProfile(name: string) {
    const profile = this.profiles.get(name);
    if (!profile) return;
    
    performance.mark(`${name}-end`);
    performance.measure(
      `${name}-total`,
      `${name}-start`,
      `${name}-end`
    );
    
    // Measure between marks
    for (let i = 0; i < profile.marks.length - 1; i++) {
      performance.measure(
        `${name}-${profile.marks[i].name}-to-${profile.marks[i + 1].name}`,
        profile.marks[i].id,
        profile.marks[i + 1].id
      );
    }
    
    return this.getProfileReport(name);
  }
  
  getProfileReport(name: string) {
    const measures = performance.getEntriesByType('measure')
      .filter(m => m.name.startsWith(name));
    
    return {
      profile: name,
      totalDuration: measures.find(m => m.name === `${name}-total`)?.duration,
      steps: measures.filter(m => m.name !== `${name}-total`).map(m => ({
        name: m.name,
        duration: m.duration
      }))
    };
  }
}

3. Memory Leak Detection

// Monitor memory usage during Claude sessions
class MemoryMonitor {
  private snapshots: any[] = [];
  private interval: number | null = null;
  
  startMonitoring(intervalMs = 5000) {
    if (!performance.memory) {
      console.warn('Memory API not available');
      return;
    }
    
    this.interval = window.setInterval(() => {
      this.snapshots.push({
        timestamp: Date.now(),
        memory: {
          usedJSHeapSize: performance.memory.usedJSHeapSize,
          totalJSHeapSize: performance.memory.totalJSHeapSize,
          jsHeapSizeLimit: performance.memory.jsHeapSizeLimit
        }
      });
    }, intervalMs);
  }
  
  stopMonitoring() {
    if (this.interval) {
      clearInterval(this.interval);
      this.interval = null;
    }
    
    return this.analyze();
  }
  
  analyze() {
    if (this.snapshots.length < 2) return null;
    
    const first = this.snapshots[0];
    const last = this.snapshots[this.snapshots.length - 1];
    
    return {
      duration: last.timestamp - first.timestamp,
      memoryGrowth: last.memory.usedJSHeapSize - first.memory.usedJSHeapSize,
      peakMemory: Math.max(...this.snapshots.map(s => s.memory.usedJSHeapSize)),
      avgMemory: this.snapshots.reduce((sum, s) => sum + s.memory.usedJSHeapSize, 0) / this.snapshots.length,
      snapshots: this.snapshots
    };
  }
}

Best Practices

1. Logging Strategy

• Use structured logging for API calls
• Include request IDs for correlation
• Log both successes and failures
• Implement log levels (debug, info, warn, error)

2. Error Handling

• Catch and log all API errors
• Include context in error messages
• Implement graceful degradation
• Use error boundaries in React applications

3. Performance Optimization

• Monitor API response times
• Implement request debouncing
• Use caching for repeated queries
• Profile memory usage for long sessions

4. Security Considerations

• Never log API keys or sensitive data
• Use secure storage for credentials
• Implement request sanitization
• Monitor for suspicious patterns

Chrome DevTools AI Features (2025)

Chrome DevTools now includes AI-powered debugging assistance:

1. Network Analysis AI: Automatically identifies API errors, CORS issues, and performance problems
2. Smart Suggestions: AI provides optimization recommendations for API calls
3. Security Scanning: Highlights potential security issues in API requests
4. Response Validation: Compares actual vs expected API responses

Access these features by clicking the “Ask AI” button in DevTools panels.

Conclusion

Effective debugging of Claude Code sessions requires a combination of browser DevTools mastery, understanding of API patterns, and systematic troubleshooting approaches. The techniques outlined here provide a comprehensive toolkit for diagnosing and resolving issues in AI-powered applications.

See Also

• Debugging Patterns
• Error Handling in TypeScript SDK
• Performance Optimization
• Error Recovery Patterns

External Resources

• Chrome DevTools Documentation
• Chrome DevTools Protocol
• MCP Server for Chrome DevTools
• Claude Code Best Practices