# `ClaudeAgentSDK.DebugMode`
[🔗](https://github.com/nshkrdotcom/claude_agent_sdk/blob/v0.21.0/lib/claude_agent_sdk/debug_mode.ex#L1)

Comprehensive debugging and diagnostics for Claude Code SDK.

This module provides tools for troubleshooting queries, analyzing performance,
and diagnosing environment issues. Essential for development, testing, and
production monitoring of Claude Code SDK usage.

## Features

- **Query Debugging**: Detailed execution logging with timing
- **Environment Diagnostics**: CLI installation and auth status checks
- **Performance Benchmarking**: Multi-run performance analysis
- **Message Analysis**: Content statistics and error detection
- **Connectivity Testing**: Basic health checks and validation

## Basic Usage

    # Debug a specific query
    messages = ClaudeAgentSDK.DebugMode.debug_query("Hello, Claude!")
    
    # Run full environment diagnostics
    ClaudeAgentSDK.DebugMode.run_diagnostics()
    
    # Benchmark query performance
    results = ClaudeAgentSDK.DebugMode.benchmark("Analyze this code", nil, 3)
    
    # Analyze message statistics
    stats = ClaudeAgentSDK.DebugMode.analyze_messages(messages)

## Debug Output Example

    🐛 DEBUG MODE ENABLED
       Prompt: "Hello, Claude!"
       Options: %ClaudeAgentSDK.Options{verbose: true, max_turns: 1}
       ✅ Auth: Authenticated as user@example.com
       [0ms] system:init: session_id=abc123, model=opus
       [1250ms] assistant: "Hello! How can I help you today?" (35 chars)
       [1680ms] result:success: cost=$0.003, turns=1
    🏁 Debug completed in 1680ms with 3 messages

## Environment Diagnostics

    🔍 Running Claude Code SDK Diagnostics...
    ✅ CLI Status: Installed at /usr/local/bin/claude
       Version: 1.2.3
    ✅ Authentication: Authenticated as user@example.com
    📋 Environment:
       Build env: dev
       Mock enabled: false
       Elixir: 1.15.0
       OTP: 26
    🔌 Testing basic connectivity...
       ✅ Basic connectivity OK
    ✅ All systems operational!

# `analyze_messages`

```elixir
@spec analyze_messages(Enumerable.t()) :: map()
```

Analyzes a stream of messages and provides comprehensive statistics.

Examines message patterns, content metrics, performance data, and error
conditions to provide insights into query execution and results.

## Parameters

- `messages` - List or stream of `ClaudeAgentSDK.Message` structs

## Returns

- Map with detailed analysis results

## Examples

    messages = ClaudeAgentSDK.query("Analyze this code")
    stats = ClaudeAgentSDK.DebugMode.analyze_messages(messages)
    
    # %{
    #   total_messages: 5,
    #   message_types: %{assistant: 2, system: 1, result: 1, user: 1},
    #   total_cost_usd: 0.025,
    #   duration_ms: 3420,
    #   content_length: 1523,
    #   tools_used: ["Read", "Grep"],
    #   session_id: "abc123",
    #   success: true,
    #   errors: []
    # }

## Analysis Fields

- `total_messages` - Count of all messages
- `message_types` - Breakdown by message type
- `total_cost_usd` - Total API cost (if available)
- `duration_ms` - Total execution time
- `content_length` - Total character count of text content
- `tools_used` - List of tools invoked during execution
- `session_id` - Session identifier
- `success` - Whether query completed successfully
- `errors` - List of any error conditions encountered

# `benchmark`

```elixir
@spec benchmark(String.t(), ClaudeAgentSDK.Options.t() | nil, pos_integer()) :: map()
```

Benchmarks a query and returns performance metrics.

## Parameters

  - `prompt` - The query prompt
  - `options` - Optional ClaudeAgentSDK.Options
  - `runs` - Number of times to run the query (default: 1)

## Returns

  - Map with benchmark results

## Examples

    iex> results = ClaudeAgentSDK.DebugMode.benchmark("Hello", nil, 3)
    %{
      runs: 3,
      avg_duration_ms: 1523,
      min_duration_ms: 1420,
      max_duration_ms: 1650,
      avg_cost_usd: 0.015
    }

# `debug_query`

```elixir
@spec debug_query(String.t(), ClaudeAgentSDK.Options.t() | nil) :: [
  ClaudeAgentSDK.Message.t()
]
```

Executes a query in debug mode with detailed logging and timing.

Provides comprehensive debug output including authentication status,
timing information for each message, and final statistics. Automatically
enables verbose mode and catches/reports any errors.

## Parameters

- `prompt` - The query prompt to debug
- `options` - Optional `ClaudeAgentSDK.Options` (verbose will be auto-enabled)

## Returns

- List of messages with complete debug trace

## Examples

    # Basic debug query
    messages = ClaudeAgentSDK.DebugMode.debug_query("Hello")
    
    # Debug with custom options
    options = %ClaudeAgentSDK.Options{max_turns: 3}
    messages = ClaudeAgentSDK.DebugMode.debug_query("Complex task", options)

## Output Format

    🐛 DEBUG MODE ENABLED
       Prompt: "Hello, Claude!"
       Options: %ClaudeAgentSDK.Options{verbose: true, max_turns: 1}
       ✅ Auth: Authenticated as user@example.com
       [0ms] system:init: session_id=abc123, model=opus
       [1250ms] assistant: "Hello! How can I help you today?" (35 chars)
       [1680ms] result:success: cost=$0.003, turns=1
    🏁 Debug completed in 1680ms with 3 messages

# `inspect_message`

```elixir
@spec inspect_message(ClaudeAgentSDK.Message.t()) :: String.t()
```

Formats a message for detailed inspection.

## Parameters

  - `message` - A ClaudeAgentSDK.Message struct

## Returns

  - Formatted string representation

## Examples

    iex> ClaudeAgentSDK.DebugMode.inspect_message(message)
    "Message[assistant]: "Hello, world!" (15 chars)"

# `profile_query`

```elixir
@spec profile_query(String.t(), ClaudeAgentSDK.Options.t() | nil) ::
  {[ClaudeAgentSDK.Message.t()], map()}
```

Executes a query with performance profiling.

Similar to `debug_query/2` but focuses on performance metrics,
memory usage, and execution timing rather than detailed content logging.

## Parameters

- `prompt` - The query prompt
- `options` - Optional `ClaudeAgentSDK.Options`

## Returns

- `{messages, profile}` where profile contains performance data

## Examples

    {messages, profile} = ClaudeAgentSDK.DebugMode.profile_query("Complex task")
    IO.puts("Peak memory: #{profile.peak_memory_mb}MB")
    IO.puts("Execution time: #{profile.execution_time_ms}ms")

# `run_diagnostics`

```elixir
@spec run_diagnostics() :: :ok
```

Runs a diagnostic check of the SDK environment.

Checks:
- CLI installation
- Authentication status
- Basic connectivity
- Environment configuration

## Examples

    iex> ClaudeAgentSDK.DebugMode.run_diagnostics()
    🔍 Running Claude Code SDK Diagnostics...
    ✅ CLI Status: Installed at /usr/local/bin/claude
    ...

---

*Consult [api-reference.md](api-reference.md) for complete listing*