Agent skill

debugging-claude-code

Troubleshooting guide for Claude Code issues. Use when Claude behaves unexpectedly, tools fail, sessions hang, or you need to diagnose problems. Covers diagnostics, common issues, and recovery procedures.

View SKILL.md on GitHub Repository
Stars 163
Forks 31

Install this agent skill to your Project

npx add-skill https://github.com/majiayu000/claude-skill-registry/tree/main/skills/data/debugging-claude-code

SKILL.md

Debugging Claude Code

Systematic troubleshooting guide for diagnosing and resolving Claude Code issues.

Quick Diagnostics

Run these commands first when experiencing issues:

bash
# Health check - comprehensive system status
claude doctor

# Or in-session
/doctor

# Check Claude Code version
claude --version

# 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

bash
# 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

bash
# View current permissions
/permissions

# Check what tools are allowed
/permissions --tools

# Check file access patterns
/permissions --files

Hook Diagnostics

bash
# 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

bash
# 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

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

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

Clear Issues

bash
# Clear conversation context
/clear

# Compact context (keep important parts)
/compact

# Reset session
/reset

Configuration Reset

bash
# 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

Recommended Agent Skills

Expand your agent's capabilities with these related and highly-rated skills.

majiayu000/claude-skill-registry

agent-ops-spec

Manage specification documents in .agent/specs/. Use when user provides requirements, acceptance criteria, or feature descriptions that need to be tracked and validated against implementation.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-state

Maintain .agent state files. Use at session start, after meaningful steps, and before concluding: read/update constitution/memory/focus/issues/baseline consistently.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-spec

Manage specification documents in .agent/specs/. Use when user provides requirements, acceptance criteria, or feature descriptions that need to be tracked and validated against implementation.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-testing

Test strategy, execution, and coverage analysis. Use when designing tests, running test suites, or analyzing test results beyond baseline checks.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-testing

Test strategy, execution, and coverage analysis. Use when designing tests, running test suites, or analyzing test results beyond baseline checks.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-state

Maintain .agent state files. Use at session start, after meaningful steps, and before concluding: read/update constitution/memory/focus/issues/baseline consistently.

163 31
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results