mcpField
C
claude-code-debug

claude-code-debug

github.com/0xdarkmatterAgent workflows7853 installsUpdated 2w ago
Repository

About claude-code-debug

A troubleshooting skill for Claude Code extensions, hooks, agents, skills, permissions, and MCP connections. It provides diagnostic commands, common checks, and validation steps for investigating unexpected behavior.

Key features

  1. 01Inspect debug output and configuration
  2. 02Check hooks, agents, and memory
  3. 03Troubleshoot skill and hook loading
  4. 04Test MCP server connections
  5. 05Run YAML and naming validations

Use cases

  1. 01Investigate a skill that will not load
  2. 02Diagnose a hook that does not run
  3. 03Check why an agent is not delegated
  4. 04Troubleshoot MCP connection failures

MCP support

The skill helps diagnose MCP server connection failures in Claude Code, including suggesting manual server tests with `npx`. It also explains that debug output can show MCP server connections.

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/0xdarkmatter/claude-mods --skill claude-code-debug

After installing, type/claude-code-debugin Claude Code to confirm it loaded.

Bundled files

References and scripts installed along with SKILL.md.

assets/
.gitkeep
references/
troubleshooting-flow.md
debug-commands.md
common-issues.md
scripts/
.gitkeep

Details

From the project README

Claude Code Debug

Troubleshoot extensions, hooks, and unexpected behavior.

Quick Diagnostics

# Enable debug mode
claude --debug

# Check loaded extensions
/hooks        # View registered hooks
/agents       # View available agents
/memory       # View loaded memory files
/config       # View current configuration

Common Issues

SymptomQuick Check
Skill not activatingVerify description has trigger keywords
Hook not runningCheck chmod +x, run /hooks
Agent not delegatingAdd "Use proactively" to description
MCP connection failsTest server manually with npx
Permission deniedCheck settings.json allow rules

Debug Mode Output

claude --debug
# Shows:
# - Hook execution and errors
# - Skill loading status
# - Subagent invocations
# - Tool permission decisions
# - MCP server connections

Quick Fixes

Skill Not Loading
# Check structure
ls -la .claude/skills/my-skill/
# Must have: SKILL.md

# Verify YAML frontmatter
head -10 .claude/skills/my-skill/SKILL.md
# Must start/end with ---

# Check name matches directory
grep "^name:" .claude/skills/my-skill/SKILL.md
Hook Not Executing
# Make executable
chmod +x .claude/hooks/my-hook.sh

# Test manually
echo '{"tool_name":"Bash"}' | .claude/hooks/my-hook.sh
echo $?  # Check exit code

# Verify JSON syntax
jq '.' ~/.claude/settings.json
Agent Not Being Used
# Check file location
ls ~/.claude/agents/
ls .claude/agents/

# Verify description includes "Use for:" or "Use proactively"
grep -i "use" agents/my-agent.md | head -5

# Explicitly request
# "Use the my-agent agent to analyze this"

Validation

# Run all validations
just test

# YAML validation only
just validate-yaml

# Name matching only
just validate-names

Official Documentation

Additional Resources

  • ./references/common-issues.md - Issue → Solution lookup table
  • ./references/debug-commands.md - All inspection commands
  • ./references/troubleshooting-flow.md - Decision tree

See Also: claude-code-hooks for hook debugging, claude-code-templates for correct structure

Comments

Markdown supported