Debug mode - verbose output for all operations

claude --debug

Environment-level debug logging

ANTHROPIC_LOG=debug claude

Check registered hooks

claude --print-hooks

View MCP server status

claude mcp list


## Common Issues Quick Reference

| Symptom | Likely Cause | Quick Fix |
|---------|--------------|-----------|
| Tool not working | Permission denied | `/permissions` then allow tool |
| MCP tools missing | Server disconnected | `/mcp` to check status |
| Hook not firing | JSON syntax error | `jq . ~/.claude/settings.json` |
| Skill not loading | Invalid frontmatter | Check YAML syntax |
| Context overflow | Too much data | Use `/compact` or `/clear` |
| Rate limited | Too many requests | Wait 60 seconds |
| API errors | Auth/network issues | Check `~/.claude/.credentials.json` |
| Session stuck | Process hanging | Ctrl+C, restart Claude |
| Slow responses | Network or model load | Check connection, try again |

## Debug Flags and Environment Variables

### Command-Line Flags

| Flag | Purpose |
|------|---------|
| `--debug` | Enable verbose debug output |
| `--print-hooks` | Display all registered hooks |
| `--verbose` | Show more detailed output |
| `--no-cache` | Disable response caching |

### Environment Variables

| Variable | Purpose | Example |
|----------|---------|---------|
| `ANTHROPIC_LOG` | Log level | `debug`, `info`, `warn`, `error` |
| `CLAUDE_CODE_DEBUG` | Additional debugging | `1` or `true` |
| `MCP_TIMEOUT` | MCP connection timeout (ms) | `30000` |
| `MAX_MCP_OUTPUT_TOKENS` | Max MCP output size | `50000` |
| `HTTP_PROXY` | Proxy for network requests | `http://proxy:8080` |
| `HTTPS_PROXY` | HTTPS proxy | `https://proxy:8080` |
| `NO_PROXY` | Skip proxy for hosts | `localhost,127.0.0.1` |

### Combined Debug Session

```bash
# Maximum verbosity
ANTHROPIC_LOG=debug claude --debug 2>&1 | tee ~/claude-debug.log

Log Locations

By Operating System

OS	Location
macOS	`~/Library/Logs/Claude Code/`
Linux	`~/.local/share/claude-code/logs/`
Windows	`%APPDATA%\Claude Code\logs\`

Configuration Files

File	Purpose
`~/.claude/settings.json`	User settings and hooks
`~/.claude/.credentials.json`	API credentials
`~/.claude/projects.json`	Project-specific settings
`.claude/settings.json`	Project settings (committed)
`.claude/settings.local.json`	Local project settings
`.mcp.json`	MCP server configuration

Session Data

Location	Contents
`~/.claude/sessions/`	Session transcripts
`~/.claude/todos/`	Task lists
`~/.claude/memory/`	Persistent memory

Diagnostic Commands

System Health

# Full health check
claude doctor

# Check component status
claude doctor --component api
claude doctor --component mcp
claude doctor --component hooks

/doctor reports (2.1.6+):

Updates section - Shows auto-update channel and available npm versions (stable/latest)
Permission warnings - Detects unreachable permission rules with fix guidance
API connectivity - Verifies connection to Anthropic API
MCP servers - Lists connected servers and their status
Hooks - Validates hook configurations

Permission Diagnostics

# View current permissions
/permissions

# Check what tools are allowed
/permissions --tools

# Check file access patterns
/permissions --files

Hook Diagnostics

# List all registered hooks
claude --print-hooks

# View hooks in interactive mode
/hooks

# Validate hook JSON
jq . ~/.claude/settings.json
jq . .claude/settings.json

MCP Diagnostics

# List configured servers
claude mcp list

# Get server details
claude mcp get <server-name>

# Check connection in session
/mcp

Diagnostic Decision Tree

Is Claude starting?

Claude won't start
    |
    +-- Check: claude --version
    |   |
    |   +-- Works --> Config issue, check ~/.claude/
    |   +-- Fails --> Installation issue, reinstall
    |
    +-- Check: ANTHROPIC_LOG=debug claude
        |
        +-- Auth error --> Check credentials
        +-- Network error --> Check connectivity
        +-- Other --> See COMMON-ISSUES.md

Are tools working?

Tool not working
    |
    +-- Check: /permissions
    |   |
    |   +-- Denied --> Allow tool
    |   +-- Allowed --> Continue
    |
    +-- Check: --debug output
    |   |
    |   +-- Tool called --> Check tool-specific logs
    |   +-- Not called --> Check permissions/syntax
    |
    +-- MCP tool?
        |
        +-- Yes --> /mcp, check server status
        +-- No --> See COMMON-ISSUES.md

Are hooks working?

Hook not firing
    |
    +-- Check: /hooks
    |   |
    |   +-- Listed --> Matcher issue or script issue
    |   +-- Not listed --> JSON syntax error
    |
    +-- Validate JSON: jq . settings.json
    |   |
    |   +-- Valid --> Check matcher pattern
    |   +-- Invalid --> Fix JSON syntax
    |
    +-- Test script: echo '{}' | ./hook.sh
        |
        +-- Works --> Matcher doesn't match
        +-- Fails --> Script error

Built-in Diagnostic Commands

Command	Purpose
`/hooks`	View registered hooks
`/mcp`	MCP server status
`/permissions`	Permission settings
`/memory`	Memory bank status
`/status`	Session status
`/bug`	Report a bug
`/doctor`	Run health checks

Verbose Mode

Toggle verbose mode during a session:

Keyboard shortcut: Ctrl+O (in terminal)
Shows: Hook execution, tool calls, API responses

Quick Fixes

Permission Issues

# Allow all file operations in project
/permissions --allow "Write,Edit,Read" --scope project

# Allow specific MCP server
/permissions --allow "mcp__servername__*"

Clear Issues

# Clear conversation context
/clear

# Compact context (keep important parts)
/compact

# Reset session
/reset

Configuration Reset

# Back up and reset settings
cp ~/.claude/settings.json ~/.claude/settings.json.bak
rm ~/.claude/settings.json

# Reset just hooks
jq 'del(.hooks)' ~/.claude/settings.json > tmp && mv tmp ~/.claude/settings.json

Reference Files

File	Contents
DIAGNOSTICS.md	Detailed diagnostic techniques
COMMON-ISSUES.md	Common problems and solutions
RECOVERY.md	Recovery procedures

When to Escalate

Use /bug to report issues when:

claude doctor shows failures
Reproducible crashes
API errors persist after credential refresh
Behavior contradicts documentation

Include in bug reports:

Claude Code version (claude --version)
OS and version
Debug output (claude --debug)
Steps to reproduce

debugging-claude-code

Debugging Claude Code

Quick Diagnostics