Claude Code ガイド

Appearance

セルフホストランナー：post-sessionライフサイクルフックとSIGTERMタイムアウト設定 ​

原文（日本語に翻訳） ​

セルフホストランナー向けに、セッション終了後かつワークスペース削除前に実行される post-session ライフサイクルフックを追加しました。これにより、コミットされていない作業のスナップショット取得やログのエクスポートが可能になります。また、子プロセスの SIGTERM→SIGKILL 待機ウィンドウを設定可能にしました（デフォルトは従来通り5秒）。

原文（英語） ​

Self-hosted runner: added a post-session lifecycle hook that runs after the session ends and before the workspace is deleted, so you can snapshot uncommitted work or export logs; also made the child-process SIGTERM→SIGKILL window configurable (default unchanged at 5s)

概要 ​

Claude Codeのセルフホストランナーに post-session ライフサイクルフックが追加されました。このフックはセッション終了後・ワークスペース削除前に実行されるため、未コミットの変更をバックアップしたり、ログをエクスポートしたりするカスタムスクリプトを差し込めます。同時に、子プロセス終了時の SIGTERM→SIGKILL 待機ウィンドウも設定可能になり、環境に合わせた柔軟なシャットダウン制御が実現します。

基本的な使い方 ​

post-sessionフックの設定 ​

セルフホストランナーの設定ファイルに post-session フックを追加します。

json
{
  "runner": {
    "hooks": {
      "post-session": "/path/to/your/post-session-script.sh"
    }
  }
}

シンプルなログエクスポートスクリプト ​

bash
#!/bin/bash
# post-session.sh

SESSION_ID="${CLAUDE_SESSION_ID}"
WORKSPACE="${CLAUDE_WORKSPACE_PATH}"
LOG_DIR="/var/log/claude-sessions"

mkdir -p "$LOG_DIR"
cp -r "$WORKSPACE/.claude/logs/" "$LOG_DIR/$SESSION_ID/" 2>/dev/null || true
echo "Session $SESSION_ID logs exported at $(date)" >> "$LOG_DIR/export.log"

SIGTERMタイムアウトの設定 ​

json
{
  "runner": {
    "sigterm_timeout_seconds": 10
  }
}

実践例 ​

未コミット作業のスナップショット ​

セッション終了時に、コミットされていない変更を自動的にバックアップする例：

bash
#!/bin/bash
# snapshot-uncommitted.sh

WORKSPACE="${CLAUDE_WORKSPACE_PATH}"
SNAPSHOT_DIR="/backups/claude-snapshots/$(date +%Y%m%d)"
SESSION_ID="${CLAUDE_SESSION_ID}"

mkdir -p "$SNAPSHOT_DIR"

cd "$WORKSPACE" || exit 0

# 未コミットの変更がある場合のみスナップショット
if ! git diff --quiet HEAD 2>/dev/null; then
    git stash create > "$SNAPSHOT_DIR/$SESSION_ID.stash_id"
    git diff HEAD > "$SNAPSHOT_DIR/$SESSION_ID.patch"
    echo "Uncommitted changes snapshotted for session $SESSION_ID"
fi

セッションメトリクスの収集 ​

bash
#!/bin/bash
# collect-metrics.sh

METRICS_ENDPOINT="https://metrics.example.com/claude-sessions"
SESSION_ID="${CLAUDE_SESSION_ID}"
SESSION_DURATION="${CLAUDE_SESSION_DURATION_SECONDS}"

curl -s -X POST "$METRICS_ENDPOINT" \
  -H "Content-Type: application/json" \
  -d "{
    \"session_id\": \"$SESSION_ID\",
    \"duration_seconds\": $SESSION_DURATION,
    \"timestamp\": \"$(date -u +%Y-%m-%dT%H:%M:%SZ)\"
  }"

クリーンアップ処理の実行 ​

bash
#!/bin/bash
# cleanup.sh

WORKSPACE="${CLAUDE_WORKSPACE_PATH}"

# 一時ファイルの削除
find "$WORKSPACE" -name "*.tmp" -delete 2>/dev/null
find "$WORKSPACE" -name ".cache" -type d -exec rm -rf {} + 2>/dev/null

# Dockerコンテナのクリーンアップ（セッション中に起動したものを停止）
if [ -n "${CLAUDE_SESSION_CONTAINERS}" ]; then
    echo "$CLAUDE_SESSION_CONTAINERS" | xargs docker stop 2>/dev/null || true
fi

SIGTERM→SIGKILL ウィンドウのカスタマイズ ​

データベース操作など、シャットダウンに時間がかかるプロセスに対して余裕を持たせる：

json
{
  "runner": {
    "sigterm_timeout_seconds": 30,
    "hooks": {
      "post-session": "/scripts/graceful-shutdown.sh"
    }
  }
}

注意点 ​

  • 実行タイミング: post-session フックはセッション終了後・ワークスペース削除前に実行されます。フックの実行中はワークスペースのファイルにアクセス可能です。
  • タイムアウト: フックスクリプトが長時間実行されると、ワークスペースの削除が遅延します。スクリプトには適切なタイムアウトを設定してください。
  • エラーハンドリング: フックスクリプトがゼロ以外の終了コードを返してもセッションの終了処理は継続されます。エラーはログに記録されます。
  • SIGTERM デフォルト値: SIGTERMタイムアウトのデフォルトは 5秒 のままです。変更が必要な場合のみ設定してください。
  • セルフホスト専用: これらの機能はセルフホストランナー環境専用です。Claude.ai のクラウド環境では利用できません。
  • 環境変数: フックスクリプト内では CLAUDE_SESSION_ID、CLAUDE_WORKSPACE_PATH などの環境変数が利用可能です（詳細は公式ドキュメントを参照）。

関連情報 ​