Debug Hooks
Debug hook failures in Claude Code with systematic diagnostics
What You Can Do
You can systematically diagnose why hooks aren't firing, producing incorrect output, or behaving unexpectedly. This skill guides you through verification steps—checking hook registration, confirming file existence, testing hooks manually, and identifying silent failures—to pinpoint the exact cause of hook breakdowns and implement targeted fixes.
Features
verify hook outputs and debug logs are being written to correct project and global directories
check .claude/settings.json at both project and global scope to confirm hooks are registered
confirm hook shell wrappers and compiled TypeScript bundles exist and are in expected locations
run hooks directly with sample JSON payloads to isolate failures outside the Claude Code runtime
identify detached spawns with stdio: 'ignore' that hide hook errors from standard output
systematically debug SessionEnd, PostToolUse, and UserPromptSubmit hooks with hook-specific test patterns
catch common mistakes like incorrect CLAUDE_PROJECT_DIR references or wrong cache paths
Example Output
Hook Registration Check:
Project settings found:
SessionEnd: /project/.claude/hooks/session-end-cleanup.sh ✓
PostToolUse: /project/.claude/hooks/handoff-index.sh ✓
Global settings: ~/.claude/settings.json also checked
Manual Hook Test:
Test input: {"tool_name": "Write", "tool_input": {"file_path": "test.md"}}
Hook execution: SUCCESS
Output written to: .claude/cache/index.json
Timestamp: 2024-01-15T14:32:11Z
Silent Failure Diagnosis:
Found detached spawn with stdio: 'ignore' in hooks/handoff-index.ts
Recommendation: Add file logging to capture errors
Debug log enabled at: .claude/cache/debug.log
What's Included
- debug-hooks.md: complete diagnostic workflow with all check commands and testing procedures
- Bash command templates: ready-to-run commands for cache inspection, hook verification, and manual testing
- JSON test payloads: example inputs for SessionEnd, PostToolUse, and UserPromptSubmit hooks
- Silent failure checklist: patterns to identify hidden errors in detached spawns and stdio configuration
- Path reference guide: clarification of $CLAUDE_PROJECT_DIR and global ~/.claude/ directory structure
Who It's For
- Claude Code developers — debugging hook integrations in AI-powered development workflows
- DevOps engineers — troubleshooting hook failures in automated code generation pipelines
- Full-stack developers — resolving hook issues in TypeScript/JavaScript Claude Code projects
- Software architects — validating hook configurations across project and global settings
- Engineering leads — systematically diagnosing hook problems before escalating to vendor support
Best For
- Debugging hooks that fail silently without errors in output
- Verifying hook registration across project and global configuration files
- Testing hook behavior in isolation before integration testing
- Identifying common path errors and stdio configuration issues
- Systematically ruling out environment and configuration problems in hook chains
You might also like
You'll transform high-level feature requirements into a complete development plan covering API design, frontend implementation, testing strategy, and documentation. The skill helps you identify dependencies, parallelize work across frontend and backend teams, and establish quality gates that ensure features ship bug-free with proper error handling and logging.
You can perform a complete audit of your project's environment variables to discover unused configurations, identify which services are integrated (Stripe, AWS, Supabase, etc.), and understand permission scopes. The skill maps exactly where each variable is used in your codebase, then optionally removes unused variables with automatic regression detection to prevent breaking changes.
by qdhenry
You can systematically analyze construction estimates by breaking down components, validating labor and material pricing against market data, identifying embedded errors or outdated assumptions, and applying data-driven contingency allocation. Claude helps you produce risk-adjusted cost projections that are defensible to stakeholders and competitive in bid scenarios, reducing estimate variance and catching pricing gaps before client submission.
by parcadei
You can rapidly process multiple subcontractor bid responses—from trade contractors, material suppliers, and specialty vendors—into a cohesive, auditable estimate structure. Claude extracts key bid components, identifies pricing inconsistencies against benchmarks or prior projects, flags scope gaps and exclusions, and organizes everything by CSI division for seamless estimate assembly. This eliminates manual spreadsheet comparison and reduces the risk of overlooked scope omissions or pricing anomalies when managing 15+ concurrent bids.
by parcadei
You can construct geometric objects (points, lines, polygons, multigeometries), execute boolean operations (intersection, union, difference), apply spatial predicates (contains, intersects, within), calculate measurements (area, length, distance, centroid), and transform geometries through translation, rotation, and scaling. This skill handles geometry validation, invalid geometry repair, and complex spatial analysis tasks.
by parcadei
You can transform fragmented cost data, subcontractor quotes, and contingency calculations into cohesive, defensible bid packages that stakeholders understand and trust. This skill guides you through hierarchical cost aggregation, dynamic contingency modeling based on project risk, multi-tier markup application, and narrative integration that links scope assumptions to pricing—enabling you to develop competitive proposals with justified pricing strategies.
by parcadei
You can paste CPM schedule exports from Primavera P6, Microsoft Project, or narrative descriptions into Claude to perform comprehensive constraint analysis and identify schedule optimization opportunities. The skill analyzes activity relationships, float distributions, resource constraints, and schedule vulnerability patterns to quantify which activities drive project completion, measure schedule buffer effectiveness, and develop quantified mitigation strategies that balance acceleration with cost and logistical feasibility.
by parcadei
You can deploy this agent to execute specific implementation tasks within a larger development plan. It operates independently with fresh context, follows test-driven development principles for every code change, and creates comprehensive handoff documentation that captures progress, decisions, and learnings for the next task executor. This ensures consistent code quality, prevents rework, and maintains continuity across distributed implementation efforts.
by parcadei