Claude Code Verbose Mode: Debug Output Guide 2026

Written by Michael Lip · Solo founder of Zovo · $400K+ on Upwork · 100% JSS Join 50+ builders · More at zovo.one

The Workflow

Enable verbose and debug output in Claude Code to inspect API requests, token usage, tool calls, and timing data. Essential for diagnosing unexpected behavior, optimizing costs, and understanding how Claude Code processes your prompts.

Expected time: 5 minutes Prerequisites: Claude Code CLI installed (v1.0+)

Setup

1. Enable Verbose Mode

# Run Claude Code with verbose flag
claude --verbose

# Or set environment variable for persistent verbose output
export CLAUDE_CODE_VERBOSE=1
claude

Verbose mode shows tool calls, file reads, and decision-making steps as they happen.

2. Enable Debug Mode for Full API Traces

# Full debug output including API request/response bodies
claude --debug

# Or via environment variable
export CLAUDE_CODE_DEBUG=1
claude

Debug mode adds raw API payloads, token counts per message, and latency measurements.

3. Log Output to a File

# Redirect verbose output to a file while keeping normal output in terminal
claude --verbose 2> claude-debug.log

# Or capture everything
claude --debug 2>&1 | tee claude-session.log

4. Configure Verbose in Settings

// ~/.claude/settings.json
{
  "verbosity": "verbose",
  "showTokenUsage": true,
  "showToolCalls": true,
  "showTimings": true
}

Persistent settings avoid passing flags every time.

5. Verify

claude --verbose --print "Hello"
# Expected output includes:
# [debug] Model: claude-sonnet-4-20250514
# [debug] Input tokens: 42
# [debug] Output tokens: 12
# [debug] Latency: 1.2s
# [debug] Cost: $0.0003
# Hello!

Usage Example

Debugging a prompt that produces unexpected behavior:

# Start with verbose to see what Claude Code is doing
claude --verbose

> Read src/config.ts and explain the database configuration

Verbose output reveals:

[tool_call] Read file: src/config.ts (245 lines, 4.2KB)
[context] Added to context: src/config.ts
[context] Total context: 1,234 tokens (of 200,000 limit)
[api_call] Sending request...
  Model: claude-sonnet-4-20250514
  System prompt: 847 tokens
  User message: 89 tokens
  Context files: 312 tokens
  Total input: 1,248 tokens
[api_response] Received in 2.3s
  Output tokens: 456
  Stop reason: end_turn
  Cost this turn: $0.0021
[session_total]
  Input tokens: 1,248
  Output tokens: 456
  Total cost: $0.0021

Diagnosing why Claude Code reads too many files:

claude --debug

> Fix the bug in the login handler

# Debug output shows:
[tool_call] Glob: src/**/*.ts (found 847 files)
[tool_call] Read file: src/auth/login.ts
[tool_call] Read file: src/auth/types.ts
[tool_call] Read file: src/middleware/auth.ts
[tool_call] Read file: src/db/users.ts
[tool_call] Read file: src/utils/crypto.ts
[tool_call] Read file: src/config/auth.ts
[context] WARNING: 6 files read, 12,400 tokens used for context

You can see Claude Code is reading 6 files. To reduce this (and costs), create a more targeted .claudeignore or more specific prompt:

> Fix the bug in src/auth/login.ts where the session token
> is not being refreshed on password change. Only modify login.ts.

Tracking costs across a session:

# Run with token tracking
claude --verbose --session "cost-audit"

# After multiple interactions, check cumulative usage
> /usage
# Output:
# Session: cost-audit
# Total input tokens: 45,230
# Total output tokens: 12,847
# Estimated cost: $0.087
# Files read: 23
# Tool calls: 31
# Duration: 14m 22s

Using verbose output for CI debugging:

#!/bin/bash
# ci-review.sh - Run code review with full logging
LOG="review-$(date +%s).log"

claude --verbose --print \
  "Review the changes in this PR for security issues. \
   Check src/api/ files only." \
  2> "$LOG"

# Parse the log for cost data
grep "Total cost" "$LOG"
grep "tool_call" "$LOG" | wc -l

Common Issues

Why This Matters

Verbose mode reveals exactly how many tokens each interaction costs. Teams using verbose output for a week typically identify 20-40% cost reduction opportunities by optimizing prompts and reducing unnecessary file reads.