session-start-hook

Claude Code 启动钩子技能

创建 SessionStart 钩子来安装依赖项，确保测试和代码检查工具在 Claude Code 会话（CLI、网页或 API）中正常工作。

钩子基础知识

输入（通过 stdin）

{
  "session_id": "abc123",
  "source": "startup|resume|clear|compact",
  "transcript_path": "/path/to/transcript.jsonl",
  "permission_mode": "default",
  "hook_event_name": "SessionStart",
  "cwd": "/workspace/repo"
}

异步模式

#!/bin/bash
set -euo pipefail

echo '{"async": true, "asyncTimeout": 300000}'

npm install

会话启动时，钩子会在后台运行。使用异步模式可以缩短延迟，但会引入竞态条件：Agent 循环可能会依赖启动钩子正在执行、但尚未完成的操作。

环境变量

可用的环境变量：

• $CLAUDE_PROJECT_DIR - 仓库根目录路径
• $CLAUDE_ENV_FILE - 用于写入环境变量的路径
• $CLAUDE_CODE_REMOTE - 如果运行在远程环境中（即网页端 Claude Code）

使用 $CLAUDE_ENV_FILE 为会话持久化变量：

echo 'export PYTHONPATH="."' >> "$CLAUDE_ENV_FILE"

使用 $CLAUDE_CODE_REMOTE 仅在远程环境中运行脚本：

if [ "${CLAUDE_CODE_REMOTE:-}" != "true" ]; then
  exit 0
fi

工作流

为此工作流中的所有任务创建待办清单，并按顺序逐项完成

1. 分析依赖项

查找依赖清单文件并分析。示例：

• package.json / package-lock.json → npm
• pyproject.toml / requirements.txt → pip/Poetry
• Cargo.toml → cargo
• go.mod → go
• Gemfile → bundler

此外，阅读相关文档（例如 README.md 等），了解环境设置的更多信息。

2. 设计钩子

创建一个用于安装依赖项的脚本。

关键原则：

• 第一版不要使用异步模式。只有用户提出要求时才切换到异步模式
• 除非用户另有要求，否则只为网页端编写钩子（参见 $CLAUDE_CODE_REMOTE）
• 钩子完成后会缓存容器状态，因此应优先采用能利用这一点的依赖安装方式（例如优先使用 npm install，而不是 npm ci）
• 保证幂等（可安全地多次运行）
• 非交互式（无需用户输入）

不要放入 SessionStart 钩子中的内容：

• 不要在用户级目录（~/.claude/skills/）和项目级目录（.claude/skills/）之间复制技能 — 这由 ./dotfiles/sync.sh 负责。

技能更新检查（缺失或过时则安装）：

SKILLS_DIR="$HOME/.claude/skills"
REPO_SKILLS_DIR="${CLAUDE_PROJECT_DIR}/dotfiles/claude/skills"
SKILLS_REPO="${AI_SKILLS_REPO:-camacho/ai-skills}"

skills_stale() {
  [[ ! -d "$SKILLS_DIR" ]] && return 0   # missing → stale
  if [[ -d "$REPO_SKILLS_DIR" ]]; then
    # Compare repo snapshot to installed — if different, stale
    ! diff -rq "$REPO_SKILLS_DIR" "$SKILLS_DIR" >/dev/null 2>&1 && return 0
  fi
  return 1  # up to date
}

if skills_stale; then
  echo "Skills missing or outdated — installing from $SKILLS_REPO..."
  if command -v npx &>/dev/null; then
    npx skills install "$SKILLS_REPO" --scope personal \
      || echo "Warning: skills install failed — project-scope skills still available" >&2
  else
    echo '{"message": "Skills are outdated but npx not found.\n\nRun: ./dotfiles/sync.sh push", "continue": true}'
  fi
fi

此检查在本地进行（使用快速的 diff）— 仅在内容过时时才访问网络。默认仓库（camacho/ai-skills）可通过 AI_SKILLS_REPO 覆盖。

Dotfiles 缺失检查（作为会话提示显示，而不是 stderr 警告）：

# Surface a visible prompt if user dotfiles are missing — informational only
if [[ ! -d "$HOME/.claude/skills" ]]; then
  echo '{"message": "~/.claude/skills not found.\n\nRun: ./dotfiles/sync.sh push\n\nThis sets up user-level skills and configs from the dotfiles repo.", "continue": true}'
  exit 0
fi

使用钩子的 JSON message 字段（而不是 stderr），可以将此提示显示在 Claude 会话上下文中，让用户看到并采取行动。"continue": true 会让会话继续运行 — 这只是提示信息，不会阻止会话。

3. 创建钩子文件

mkdir -p .claude/hooks
cat > .claude/hooks/session-start.sh << 'EOF'
#!/bin/bash
set -euo pipefail

echo '{"async": true, "asyncTimeout": 300000}'
# Install dependencies here
EOF

chmod +x .claude/hooks/session-start.sh

4. 在设置中注册

添加到 .claude/settings.json（如果文件不存在则创建）：

{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/session-start.sh"
          }
        ]
      }
    ]
  }
}

如果 .claude/settings.json 已存在，请合并 hooks 配置。

5. 验证钩子

直接运行钩子脚本：

CLAUDE_CODE_REMOTE=true ./.claude/hooks/session-start.sh

重要：确认依赖项已安装，并且脚本成功运行。

6. 验证代码检查工具

重要：确定运行代码检查工具的正确命令，并对示例文件运行。无需检查整个项目。如果发现问题，请相应更新启动脚本并重新测试。

7. 验证测试

重要：确定运行测试的正确命令，并运行一个测试。无需运行整个测试套件。如果发现问题，请相应更新启动脚本并重新测试。

8. 提交并推送

创建提交并将其推送到远程分支

收尾

全部完成。在发给用户的最后一条消息中，请按照以下格式向用户提供详细摘要：

• 更改摘要
• 验证结果
  1. 会话钩子执行情况（如果失败，请说明详情）
  2. 代码检查器执行情况（如果失败，请说明详情）
  3. 测试执行情况（如果失败，请说明详情）
• 钩子执行模式：同步
  • 告知用户钩子以同步方式运行，并说明以下权衡。让用户知道，如果他们希望更快地启动会话，我们可以将其改为异步。
    • 优点：确保在会话启动前安装好依赖项，避免 Claude 在依赖项就绪前尝试运行测试或代码检查器而导致的竞态条件
    • 缺点：远程会话只有在会话启动钩子完成后才会启动
• 告知用户，将会话启动钩子合并到仓库的默认分支后，所有未来的会话都会使用它。