Diagnose Claude Code hooks, scripts triggered by events, when they fail to run or produce unexpected results. Follow checks for logs, registration, files, manual execution, hidden errors, and rebuilt TypeScript bundles to narrow down the cause.
中文简介正在准备中。当前显示英语简介。
Systematic hook debugging workflow. Use when hooks aren't firing, producing wrong output, or behaving unexpectedly.
安装前可以查看交给 AI 代理的指令内容。
Systematic workflow for debugging Claude Code hooks.
# Check project cache
ls -la $CLAUDE_PROJECT_DIR/.claude/cache/
# Check specific outputs
ls -la $CLAUDE_PROJECT_DIR/.claude/cache/learnings/
# Check for debug logs
tail $CLAUDE_PROJECT_DIR/.claude/cache/*.log 2>/dev/null
# Also check global (common mistake: wrong path)
ls -la ~/.claude/cache/ 2>/dev/null
# Project settings
cat $CLAUDE_PROJECT_DIR/.claude/settings.json | grep -A 20 '"SessionEnd"\|"PostToolUse"\|"UserPromptSubmit"'
# Global settings (hooks merge from both)
cat ~/.claude/settings.json | grep -A 20 '"SessionEnd"\|"PostToolUse"\|"UserPromptSubmit"'
# Shell wrappers
ls -la $CLAUDE_PROJECT_DIR/.claude/hooks/*.sh
# Compiled bundles (if using TypeScript)
ls -la $CLAUDE_PROJECT_DIR/.claude/hooks/dist/*.mjs
# SessionEnd hook
echo '{"session_id": "test-123", "reason": "clear", "transcript_path": "/tmp/test"}' | \
$CLAUDE_PROJECT_DIR/.claude/hooks/session-end-cleanup.sh
# PostToolUse hook (Write tool example)
echo '{"tool_name": "Write", "tool_input": {"file_path": "test.md"}, "session_id": "test-123"}' | \
$CLAUDE_PROJECT_DIR/.claude/hooks/handoff-index.sh
If using detached spawn with stdio: 'ignore':
// This pattern hides errors!
spawn(cmd, args, { detached: true, stdio: 'ignore' })
Fix: Add temporary logging:
const logFile = fs.openSync('.claude/cache/debug.log', 'a');
spawn(cmd, args, {
detached: true,
stdio: ['ignore', logFile, logFile] // capture stdout/stderr
});
If you edited TypeScript source, you MUST rebuild:
cd $CLAUDE_PROJECT_DIR/.claude/hooks
npx esbuild src/session-end-cleanup.ts \
--bundle --platform=node --format=esm \
--outfile=dist/session-end-cleanup.mjs
Source edits alone don't take effect - the shell wrapper runs the bundled .mjs.
| Symptom | Likely Cause | Fix |
|---|---|---|
| Hook never runs | Not registered in settings.json | Add to correct event in settings |
| Hook runs but no output | Detached spawn hiding errors | Add logging, check manually |
| Wrong session ID | Using "most recent" query | Pass ID explicitly |
| Works locally, not in CI | Missing dependencies | Check npx/node availability |
| Runs twice | Registered in both global + project | Remove duplicate |
ls -la .claude/cache/)grep -A10 '"hooks"' .claude/settings.json)ls .claude/hooks/*.sh)ls -la .claude/hooks/dist/)echo '{}' | ./hook.sh)stdio: 'ignore')Derived from 10 sessions (83% of all learnings):
还没有评价。欢迎分享你的使用感受。
无需登录即可发表。欢迎分享使用感受、提问，或说明在哪些环境下无法运行。
还没有评论。来写第一条吧。
Coordinate background agents through saved files, keeping lengthy work transcripts out of the main conversation. It defines how to pass results between agents, monitor progress, and verify completed work with tests.
中文简介正在准备中。当前显示英语简介。
Delegate implementation, file reading, and testing to separate agents, then bring concise summaries back to the main conversation. The rules explain when delegation helps and when a small edit is better handled directly.
中文简介正在准备中。当前显示英语简介。
Organize implementation work across research, planning, validation, implementation, and review agents. Each stage passes files to the next, while implementation starts with failing tests and the main conversation coordinates the workflow.
中文简介正在准备中。当前显示英语简介。
Connect Agentica SDK agents to Claude Code CLI through a proxy, an intermediary server. Use setup and debugging guidance to address file permissions, streamed responses, result formatting, and agents reporting success without performing the requested operations.
中文简介正在准备中。当前显示英语简介。
Consult Agentica APIs when building workflows where multiple AI agents cooperate. This reference covers eleven coordination patterns, agent tracking, shared state, handoffs, and ways to combine results, with pointers to detailed API specifications.
中文简介正在准备中。当前显示英语简介。
Write clearer instructions for Agentica and REPL agents by specifying roles, file operations, and output formats. Includes templates for dividing research, coordinating specialists, reviewing solutions, and passing results between agents through files.
中文简介正在准备中。当前显示英语简介。