@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 ClaudeCodeSDK.Message structs

Returns

• Map with detailed analysis results

Examples

messages = ClaudeCodeSDK.query("Analyze this code")
stats = ClaudeCodeSDK.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

@spec benchmark(String.t(), ClaudeCodeSDK.Options.t() | nil, pos_integer()) :: map()

Benchmarks a query and returns performance metrics.

Parameters

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

Returns

• Map with benchmark results

Examples

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

@spec debug_query(String.t(), ClaudeCodeSDK.Options.t() | nil) :: [
  ClaudeCodeSDK.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 ClaudeCodeSDK.Options (verbose will be auto-enabled)

Returns

• List of messages with complete debug trace

Examples

# Basic debug query
messages = ClaudeCodeSDK.DebugMode.debug_query("Hello")

# Debug with custom options
options = %ClaudeCodeSDK.Options{max_turns: 3}
messages = ClaudeCodeSDK.DebugMode.debug_query("Complex task", options)

Output Format

🐛 DEBUG MODE ENABLED
   Prompt: "Hello, Claude!"
   Options: %ClaudeCodeSDK.Options{verbose: true, max_turns: 1}
   ✅ Auth: Authenticated as user@example.com
   [0ms] system:init: session_id=abc123, model=claude-opus-4
   [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

@spec inspect_message(ClaudeCodeSDK.Message.t()) :: String.t()

Formats a message for detailed inspection.

Parameters

• message - A ClaudeCodeSDK.Message struct

Returns

• Formatted string representation

Examples

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

@spec profile_query(String.t(), ClaudeCodeSDK.Options.t() | nil) ::
  {[ClaudeCodeSDK.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 ClaudeCodeSDK.Options

Returns

• {messages, profile} where profile contains performance data

Examples

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

@spec run_diagnostics() :: :ok

Runs a diagnostic check of the SDK environment.

Checks:

• CLI installation
• Authentication status
• Basic connectivity
• Environment configuration

Examples

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