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 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 systematically investigate application failures by examining logs, querying database state, and reviewing git history to identify root causes. This skill helps you understand the current state of your system without making changes, providing the contextual foundation needed to solve bugs efficiently during manual testing or implementation work.
by parcadei
You can formally verify mathematical proofs by translating theorems into Lean 4 code, leveraging Mathlib's extensive library of formalized mathematics. The skill guides you through researching existing lemmas, designing proof strategies, testing approaches, implementing formal proofs, and verifying correctness—turning informal mathematical claims into machine-checked theorems without requiring deep Lean syntax expertise.
by parcadei
Discover what tools, workflows, specialist agents, and automation hooks are available in your workspace through interactive prompts and organized catalogs. Based on your goal—whether exploring codebases, fixing bugs, building features, or proving mathematical theorems—the skill surfaces the exact capabilities you need.
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