session-start-hook

Claude Code 用スタートアップフックスキル

Claude Code のセッション（CLI、Web、API）でテストやリンターが動作するよう、依存関係をインストールする SessionStart フックを作成します。

フックの基本

入力（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

セッションの開始中、フックはバックグラウンドで実行されます。非同期モードを使うと遅延を減らせますが、スタートアップフックが完了する前にエージェントのループがフックで実行中の処理に依存する可能性があるという競合状態が発生します。

環境変数

利用可能な環境変数：

• $CLAUDE_PROJECT_DIR - リポジトリのルートパス
• $CLAUDE_ENV_FILE - 環境変数を書き込むファイルのパス
• $CLAUDE_CODE_REMOTE - リモート環境（つまり、Web 上の Claude Code）で実行中かどうか

$CLAUDE_ENV_FILE を使って、セッション用の変数を保持します：

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

$CLAUDE_CODE_REMOTE を使って、リモート環境でのみスクリプトを実行します：

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

ワークフロー

このワークフローのすべてのタスクについて ToDo リストを作成し、順番に進めてください。

1. 依存関係を分析する

依存関係のマニフェストを見つけて分析します。例：

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

また、環境のセットアップ方法について追加の情報が得られるか確認するため、ドキュメント（README.md など）も読んでください。

2. フックを設計する

依存関係をインストールするスクリプトを作成します。

重要な原則：

• 最初のイテレーションでは非同期モードを使わないでください。ユーザーから要求された場合にのみ切り替えます。
• 特に要求がない限り、Web 用のフックのみを作成します（$CLAUDE_CODE_REMOTE を参照）。
• フックの完了後にコンテナの状態がキャッシュされます。そのキャッシュを活用できるインストール方法を優先してください（つまり、npm ci より npm install を優先します）。
• 冪等にしてください（複数回実行しても安全）。
• 非対話型にしてください（ユーザー入力なし）。

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 が存在する場合は、フックの設定をマージします。

5. フックを検証する

フックスクリプトを直接実行します：

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

重要：依存関係がインストールされ、スクリプトが正常に完了することを確認してください。

6. リンターを検証する

重要：リンターを実行する適切なコマンドを確認し、サンプルファイルに対して実行してください。プロジェクト全体を lint する必要はありません。問題があれば、スタートアップスクリプトを更新して再テストしてください。

7. テストを検証する

重要：テストを実行する適切なコマンドを確認し、テストを1つ実行してください。テストスイート全体を実行する必要はありません。問題があれば、スタートアップスクリプトを更新して再テストしてください。

8. コミットしてプッシュする

変更をコミットし、リモートブランチにプッシュします。

作業のまとめ

作業はすべて完了しました。ユーザーへの最後のメッセージでは、以下の形式で詳細な概要を伝えてください。

• 変更内容の概要
• 検証結果
  1. セッションフックの実行（失敗した場合は詳細を記載）
  2. リンターの実行（失敗した場合は詳細を記載）
  3. テストの実行（失敗した場合は詳細を記載）
• フックの実行モード：同期
  • フックは同期実行され、以下のトレードオフがあることをユーザーに伝えてください。セッションの起動を速くしたい場合は、非同期に変更できることも伝えてください。
    • メリット：セッションの開始前に依存関係がインストールされることが保証されるため、Claude がテストやリンターを実行しようとしたときに、依存関係がまだ準備できていないという競合状態を防げます。
    • デメリット：セッション開始フックが完了するまで、リモートセッションは開始されません。
• セッション開始フックをリポジトリのデフォルトブランチにマージすると、今後のすべてのセッションでそのフックが使用されることをユーザーに伝えてください。