mcpField
S
setup-auto-handoff

setup-auto-handoff

github.com/dyritsエージェントワークフロー037 回インストール今日更新
リポジトリ

setup-auto-handoff について

setup-auto-handoff は、直近の引き継ぎファイルがない場合に圧縮を止める Claude Code スキルです。PreCompact フックを使い、OpenCode と Codex でのトランスクリプトを利用した代替手段も説明します。

主な機能

  1. 01直近の引き継ぎがない圧縮をブロック
  2. 02hand-off スキルの呼び出し
  3. 03設定と検証の手順
  4. 04OpenCode と Codex の代替手段

活用シーン

  1. 01Claude Code の圧縮前にコンテキストを引き継ぐ
  2. 02PreCompact フックの設定とテスト
  3. 03OpenCode または Codex での引き継ぎ管理

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/dyrits/skills --skill setup-auto-handoff

インストール後、Claude Code で/setup-auto-handoffを入力して読み込まれたか確認します。

同梱ファイルagents/openai.yamlscripts/precompact-handoff-gate.sh

詳細

自動ハンドオフのセットアップ

コンパクションを制御します。Claude Code が（自動または手動で）コンパクションを実行しようとすると、過去 5 分以内に .agents/handoffs/ にハンドオフが書き込まれていない限り、PreCompact フックがブロックします。ブロック理由には、まず hand-off スキルを実行するようエージェントに指示が表示されます。ハンドオフが作成された後のコンパクション試行は通過します。

呼び出すスキル： hand-off。呼び出したスキルがインストールされていない場合は、スキル名とインストールコマンド npx skills@latest add Dyrits/SKILLS --skill=<name> をユーザーに伝え、そのスキルが示す意図に沿って手順を実行し、スキルを使わずに手順を完了したことを報告します。

対応環境

  • Claude Code：完全対応（PreCompact フック）。このセットアップの主な対象です。
  • OpenCode / Codex：コンパクション前のフックはありません。代替手段は、保存されたトランスクリプト（codex resume、OpenCode のセッションストレージ）と、フェーズの区切りでユーザーが hand-off を実行する習慣です。この点をユーザーにはっきり伝えてください。対応しているかのように装ってはいけません。

手順

1. フックスクリプトをコピーする

同梱のスクリプトは scripts/precompact-handoff-gate.sh にあります。

.claude/hooks/precompact-handoff-gate.sh にコピーし、実行可能にします（chmod +x）。

ブロックメッセージでは hand-off を呼び出します。ゲートを問題なく機能させるには、このスキルがスキル一覧に含まれている必要があります。含まれていない場合は、まずインストールするよう勧めてください。フォールバックとしてメッセージに示される方法（ハンドオフファイルを直接書き込む方法）でも、スキルがなくてもコンパクションを続行できます。

2. フックを登録する

.claude/settings.json（プロジェクトスコープ。フックのスコープをこれより狭くすることはできません）で、既存の hooks オブジェクトにマージします。

{
  "hooks": {
    "PreCompact": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/precompact-handoff-gate.sh"
          }
        ]
      }
    ]
  }
}

ほかのフックを上書きせず、配列にマージしてください。

3. 確認する
  • .claude/hooks/precompact-handoff-gate.sh が存在し、実行可能である
  • .claude/settings.json が解析可能で（jq . .claude/settings.json）、PreCompact エントリを含んでいる
  • 新しいハンドオフがない状態で自動コンパクションをシミュレートする：
echo '{"trigger":"auto"}' | .claude/hooks/precompact-handoff-gate.sh; echo "exit: $?"

標準出力に JSON の decision: block が表示され、終了コードが 0 になることを確認します。

  • 新しいハンドオフがある状態でシミュレートする：
mkdir -p .agents/handoffs && touch .agents/handoffs/test.md
echo '{"trigger":"auto"}' | .claude/hooks/precompact-handoff-gate.sh; echo "exit: $?"
rm .agents/handoffs/test.md

出力が空で、終了コードが 0 になることを確認します。

4. 一連の流れをユーザーに説明する

コンテキストの上限に達すると、自動コンパクションが実行され、フックが指示を出してブロックします。エージェントが hand-off を実行すると、新しいファイルが .agents/handoffs/ に作成されます。その後、コンパクションが再試行され、通過します。コンパクションを完全に無効にしたい場合は、ユーザーが .claude/settings.json からフックを削除できます。手動の /compact も同じように制御されます。/clear には影響しません（別のイベントです）。

注意事項

  • 5 分の鮮度期間により、1 時間前の古いハンドオフがゲートを通過させるのを防ぎます。調整するには、スクリプト内の FRESH_WINDOW_MINUTES を編集します。
  • ゲートは .agents/handoffs/ が存在しない場合に作成するため、最初にブロックされたコンパクションが最初のハンドオフにもなります。
  • このフックには PATH 上の jq が必要です。存在しない場合は確認してユーザーに伝えてください。

コメント

Markdown 対応