Claude Code 钩子调试指南：解决钩子未触发、SessionEnd不工作等常见问题

debug-hooks by parcadei/continuous-claude-v3

202 周安装量

3,600 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/parcadei/continuous-claude-v3 --skill debug-hooks

自动化命令行工具调试

🇨🇳中文介绍

调试钩子

用于调试 Claude Code 钩子的系统化工作流程。

何时使用

"钩子未触发"
"钩子产生错误输出"
"SessionEnd 不工作"
"PostToolUse 钩子未触发"
"为什么我的钩子没有运行？"

工作流程

1. 首先检查输出（编辑前先观察）

# 检查项目缓存
ls -la $CLAUDE_PROJECT_DIR/.claude/cache/

# 检查特定输出
ls -la $CLAUDE_PROJECT_DIR/.claude/cache/learnings/

# 检查调试日志
tail $CLAUDE_PROJECT_DIR/.claude/cache/*.log 2>/dev/null

# 同时检查全局缓存（常见错误：路径错误）
ls -la ~/.claude/cache/ 2>/dev/null

2. 验证钩子注册

# 项目设置
cat $CLAUDE_PROJECT_DIR/.claude/settings.json | grep -A 20 '"SessionEnd"\|"PostToolUse"\|"UserPromptSubmit"'

# 全局设置（钩子会从两者合并）
cat ~/.claude/settings.json | grep -A 20 '"SessionEnd"\|"PostToolUse"\|"UserPromptSubmit"'

3. 检查钩子文件是否存在

# Shell 包装脚本
ls -la $CLAUDE_PROJECT_DIR/.claude/hooks/*.sh

# 编译后的包（如果使用 TypeScript）
ls -la $CLAUDE_PROJECT_DIR/.claude/hooks/dist/*.mjs

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

4. 手动测试钩子

# SessionEnd 钩子
echo '{"session_id": "test-123", "reason": "clear", "transcript_path": "/tmp/test"}' | \
  $CLAUDE_PROJECT_DIR/.claude/hooks/session-end-cleanup.sh

# PostToolUse 钩子（Write 工具示例）
echo '{"tool_name": "Write", "tool_input": {"file_path": "test.md"}, "session_id": "test-123"}' | \
  $CLAUDE_PROJECT_DIR/.claude/hooks/handoff-index.sh

5. 检查静默失败

如果使用 stdio: 'ignore' 进行分离式生成：

// 这种模式会隐藏错误！
spawn(cmd, args, { detached: true, stdio: 'ignore' })

修复方法： 添加临时日志记录：

const logFile = fs.openSync('.claude/cache/debug.log', 'a');
spawn(cmd, args, {
  detached: true,
  stdio: ['ignore', logFile, logFile]  // 捕获 stdout/stderr
});

6. 编辑后重新构建

如果你编辑了 TypeScript 源代码，必须重新构建：

cd $CLAUDE_PROJECT_DIR/.claude/hooks
npx esbuild src/session-end-cleanup.ts \
  --bundle --platform=node --format=esm \
  --outfile=dist/session-end-cleanup.mjs

仅编辑源代码不会生效 - shell 包装脚本运行的是打包后的 .mjs 文件。

症状	可能原因	修复方法
钩子从未运行	未在 settings.json 中注册	在设置的正确事件中添加
钩子运行但无输出	分离式生成隐藏了错误	添加日志记录，手动检查
会话 ID 错误	使用了"最近一次"查询	显式传递 ID
本地工作，CI 中不工作	缺少依赖项	检查 npx/node 可用性
运行两次	在全局和项目中重复注册	移除重复项

输出存在吗？ (ls -la .claude/cache/)
注册了吗？ (grep -A10 '"hooks"' .claude/settings.json)
文件存在吗？ (ls .claude/hooks/*.sh)
包是最新的吗？ (ls -la .claude/hooks/dist/)
手动测试有效吗？ (echo '{}' | ./hook.sh)
没有静默失败吗？（检查是否有 stdio: 'ignore'）

源自 10 个会话（占所有学习记录的 83%）：

a541f08a, 1c21e6c8, 6a9f2d7a, a8bd5cea, 2ca1a178, 657ce0b2, 3998f3a2, 2a829f12, 0b46cfd7, 862f6e2c

2026 年 1 月 22 日

🇺🇸English

Debug Hooks

Systematic workflow for debugging Claude Code hooks.

When to Use

"Hook isn't firing"
"Hook produces wrong output"
"SessionEnd not working"
"PostToolUse hook not triggering"
"Why didn't my hook run?"

Workflow

1. Check Outputs First (Observe Before Editing)

# 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

2. Verify Hook Registration

# 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"'

3. Check Hook Files Exist

# Shell wrappers
ls -la $CLAUDE_PROJECT_DIR/.claude/hooks/*.sh

# Compiled bundles (if using TypeScript)
ls -la $CLAUDE_PROJECT_DIR/.claude/hooks/dist/*.mjs

4. Test Hook Manually

# 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

5. Check for Silent Failures

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
});

6. Rebuild After Edits

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.

Common Issues

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

Debug Checklist

Outputs exist? (ls -la .claude/cache/)
Registered? (grep -A10 '"hooks"' .claude/settings.json)
Files exist? (ls .claude/hooks/*.sh)
Bundle current? (ls -la .claude/hooks/dist/)
Manual test works? (echo '{}' | ./hook.sh)
No silent failures? (check for stdio: 'ignore')

Source Sessions

Derived from 10 sessions (83% of all learnings):

a541f08a, 1c21e6c8, 6a9f2d7a, a8bd5cea, 2ca1a178, 657ce0b2, 3998f3a2, 2a829f12, 0b46cfd7, 862f6e2c

Weekly Installs

202

Repository

parcadei/contin…laude-v3

GitHub Stars

3.6K

First Seen

Jan 22, 2026

Security Audits

Gen Agent Trust HubPass SocketPass SnykPass

Installed on

opencode193

codex191

cursor189

gemini-cli187

github-copilot185

amp178

通过 LiteLLM 代理让 Claude Code 对接 GitHub Copilot 运行 | 高级变通方案指南

31,600 周安装