claude-handoff

あらゆる Claude Code セッション（クラッシュしたものも含む）を、別の AI が続きから作業できるクリーンな handoff.md に変換します。さらに、自身の履歴から抽出した Claude Code 用の永続的なプロジェクトメモリも提供します。

chf

これだけです。最新のセッションが handoff.md になります。ノイズのない会話、変更されたファイル、実行されたコマンド。受け取る側のアシスタントへの指示で始まるので、Gemini、GPT、claude.ai、または新しい Claude Code セッションに追加のプロンプトなしでそのまま貼り付けられます。

Claude Code はすべてのセッションをローカルの JSONL（~/.claude/projects/…/*.jsonl）として保存します。そこにはツール呼び出し、ツール結果、思考ブロック、システムリマインダーが満載です。既存のエクスポーターはそれらすべてをマークダウンに出力します。一方 claude-handoff はハンドオフドキュメントを生成します。さらに、全履歴を読み取れるため、プロジェクトメモリブリーフも生成します。

• 依存関係ゼロ。 標準ライブラリのみ、Python 3.9+。9モジュールのパッケージ — 生成済みの単一ファイルスクリプトとしても提供され、curl で取得して監査できます。

• デフォルトで決定的。 API 呼び出しなし、コストなし、オフラインで動作。

• 本当の要約が欲しいときは --llm。 自分の API キーで Claude、OpenAI、Gemini を使用 — または --llm claude-cli で、ローカルにインストールされた Claude Code CLI を既存の Pro/Max プランで実行：API キーは不要です。

• ノイズフリー。 ツール結果、思考ブロック、システムリマインダー、サブエージェントのやり取り、スラッシュコマンドのラッパーを除去。ユーザーの意図、アシスタントの回答、変更されたファイル、実行されたコマンドを保持 — サブエージェント（agent-*.jsonl）のファイルとコマンドも含み、その完全なトランスクリプトは --include-sidechains の背後に残ります。

• プロジェクトメモリ。 chf --brief はプロジェクトの全セッション履歴を1つの生きたブリーフ（決定事項、修正、規約、未解決のスレッド — セッション引用付き）に凝縮します。--install-brief-hook はそれをすべての新しい Claude Code セッションに注入し、Claude がプロジェクトを既に知った状態で開始します。

• 貼り付けても安全。 秘密文字列（API キー、トークン、password= など）はすべての出力から編集されます — Web チャットに貼り付けるハンドオフも外部送信です。--anonymize は公開共有用にさらに進みます。

前提条件

サードパーティの Python パッケージは一切不要 — すべて標準ライブラリで動作します。

Related MCP server: Longhand

インストール

pipx install claude-handoff        # or: pip install claude-handoff

brew install Vasilispapg/tap/claude-handoff   # Homebrew

# or just grab the generated single-file build — stdlib-only, auditable:
curl -O https://raw.githubusercontent.com/Vasilispapg/claude-handoff/main/single/claude_handoff.py
python3 claude_handoff.py --list

パッケージをインストールすると、claude-handoff と短いエイリアス chf の2つの同一コマンドが使えます。タブ補完：

eval "$(claude-handoff --completions zsh)"    # bash works too

60秒：あなたの状況に合わせて選択

セッションがクラッシュした、使用制限に達した、またはターミナルを閉じてしまった：

chf -o clipboard

…その後、claude.ai、ChatGPT、Gemini — または新しい claude セッションに貼り付けます。過去のセッションならどれでも動作します。クラッシュ前に何かをインストールしておく必要はありません。

Claude Code から別のモデルへ作業を移す：

chf --fit 32k -o clipboard         # sized to the receiver's context window

「CORS について話したのはどのセッションだったっけ？」

chf --list --grep "CORS"           # every match, with a 🔍 context preview
chf --grep "CORS"                  # or export the newest match directly

Claude Code にこのプロジェクトの永続的なメモリを与える：

chf --brief --llm claude-cli       # distill ALL sessions → one cited brief
chf --install-brief-hook           # every new session starts knowing it

トランスクリプトの代わりに本当の要約（目標 / 決定事項 / 状態 / 次のステップ）：

chf --llm claude-cli               # your Claude Code login — no API key

ターミナルセッションではなく claude.ai や ChatGPT の Web チャット：

chf conversations.json --list      # each app's data export works as input
chf conversations.json --name "webhook bug"

プロジェクトメモリ（--brief）

Claude Code はセッション間ですべてを忘れます — しかし全履歴はディスク上にあります。chf --brief は現在のプロジェクトのすべてのセッションを読み取り、1つのメモリドキュメントを ~/.claude/briefs/<project>.md に書き込みます：

• 事実に基づくセッションタイムライン + 最も頻繁に触れたファイル（決定的、無料）;

• --llm を使用すると、凝縮されたメモリ — 理由付きの決定事項、修正されたバグ、規約、未解決のスレッド — 各箇条書きが出典のセッション ID 付きで引用されます（chf --name <id> でソースを開きます）。

セッションごとのノートはキャッシュされるため、新しいセッション後の更新では新しいものだけにコストがかかります。また、巨大なセッション（約12万文字超）はノート内でマップリデュースされるため、メモリパスが切り詰められることはありません。どのサイズでも何も黙って破棄されません。

chf --install-brief-hook

2つのフックをインストールします：SessionStart はブリーフをコンテキストとして注入し（Claude はプロジェクトを既に知った状態で開始 — /compact 後にも再注入されます）、SessionEnd は事実部分を無料で自動更新します。フックから LLM が実行されることは決してありません。凝縮部分はあなたが明示的に指示したときだけ更新されます。ブリーフには鮮度スタンプが付き、ファイルと注入の両方が新しいセッションの存在を警告します。完全にローカル。編集は他の場所と同様に適用されます。

→ ステップバイステップの仕組み、正直なコスト表、1日使ってみたウォークスルー：docs/GUIDE.md。

自動化する

chf --install-hook                 # SessionEnd + PreCompact → handoff to ~/.claude/handoffs/
chf --install-brief-hook           # SessionStart/End + PreCompact → project memory (above)

PreCompact が重要な理由：Claude Code が長いセッションのコンテキストを圧縮する直前に、両方のフックが状態をスナップショットします — ハンドオフは圧縮がまさに絞り出そうとしている詳細を保持し、ブリーフの骨格はセッション中も新鮮なままです。

どちらも ~/.claude/settings.json を非破壊的に編集し、冪等で、対応する --uninstall-* フラグがあります。フックの失敗がホストセッションを壊すことはなく、フックが LLM 呼び出しをトリガーしたり、単独でファイルを作成したりすることもありません。

出力の見た目

# Conversation handoff

> To the receiving assistant: … you are taking over …

## Session
- Project: /home/you/myapp (branch main)
- When: 2026-08-20 09:00 → 09:04
- Activity: 2 user messages, 4 assistant replies, 4 tool calls

## Files created / modified
- /home/you/myapp/auth.py

## Commands run
- python -m pytest tests/test_auth.py -q

_🤖 2 subagent(s) contributed to the work above (--include-sidechains for their transcripts)._

## Conversation
### 🧑 User
the login breaks on unicode passwords…
### 🤖 Assistant
Found it — ascii encoding. Changed to utf-8, tests pass.

よく使うコマンド

chf                                # latest session → handoff.md
chf -i                             # numbered picker; "1,3" or "2-4" merges several
chf --list                         # what sessions do I have? (title · first prompt)
chf --list --format json           # the same, machine-readable
chf --name "login bug"             # newest session whose title/prompt matches
chf "login bug"                    # same — a non-path argument is a name search
chf --grep "CORS"                  # newest session that *talked about* CORS
chf --grep CORS --grep auth        # …that talked about BOTH (AND)
chf a.jsonl b.jsonl                # several paths → ONE merged handoff
chf --project myrepo               # latest session of a specific project
chf path/to/session.jsonl -o -     # explicit file → stdout
chf -o clipboard                   # straight to the clipboard — go paste it
chf --last 5                       # only the last 5 user turns
chf --since 2h                     # only the last 2 hours of the session
chf --fit 32k                      # sized to fit a 32k-token context
chf --include-tools                # keep collapsed per-tool-call detail
chf --include-sidechains           # append full subagent transcripts
chf --anonymize                    # public-safe: ~ paths, no emails/IPs/username
chf --project myrepo --merge       # whole project in ONE handoff, oldest → newest
chf --format json -o session.json  # machine-readable handoff

# LLM summaries (goal / decisions / current state / next steps):
chf --llm claude-cli               # your Claude Code login — no API key
chf --llm ollama                   # local model — fully offline
chf --llm claude                   # Anthropic API   (ANTHROPIC_API_KEY)
chf --llm openai --model gpt-4o    # OpenAI API      (OPENAI_API_KEY)
chf --llm gemini --with-transcript # Google API      (GEMINI_API_KEY)
chf --llm claude-cli --focus "emphasize the API decisions"

# project memory:
chf --brief                        # free factual brief (timeline + files)
chf --brief --llm claude-cli       # + distilled decisions/fixes/conventions

どこを探すの？ セッションは Claude Code のグローバルストア（~/.claude/projects）にあるため、chf はどこからでも実行できます。現在のディレクトリがプロジェクト（またはそのサブフォルダ）の場合、そのプロジェクトのセッションにスコープされます。親の「マスターフォルダ」の場合はその下のすべてのプロジェクトにスコープされます。--any はディレクトリを完全に無視します。自動選択はほぼ空のセッション（claude /login が残すスタブなど）をスキップするため、「最新」は最新の実際の会話を意味します — 明示的なパス、--name、-i は常に優先されます。

大きなセッション。 1パス（約40万文字）を超えるトランスクリプトはマップリデュース方式で要約されます：チャンクごとのノート、その後1つの統合 — 何も黙って破棄されず、完了したチャンクは ~/.cache/claude-handoff にキャッシュされるため、中断された実行は無料で再開できます。チャンクは API プロバイダーで4並列で実行されます。claude-cli と ollama は設計上逐次実行のままです。ターミナルではライブのプログレスバーが表示されます：

[█████████░░░░░░░░░░░░░░░] 3/9 chunks | 4m12s elapsed | ~8m left | summarizing part 4/8 (199,867 chars)…

API の usage データがあるセッションにはヘッダーにトークン行も追加され、毎回の実行で出力の約トークンサイズが報告されます。

プライバシーとゼロトラスト

• --llm を渡さない限り、どこにも何も送信されません — 決定的モードは完全にオフラインです。

• 編集は LLM トラフィックだけでなく、すべての出力に適用されます：秘密文字列（API キー、トークン、JWT、password= など）はハンドオフ自体、フックファイル、MCP 応答から除去されます — 貼り付けられたドキュメントも外部送信だからです。--no-redact は実行ごとにオプトアウトします（設定ファイルでは意図的に許可されていません）。

• --anonymize はさらに、ホームディレクトリを ~ に変換し、メールアドレス、IPv4、ユーザー名をプレースホルダーに置き換えます — 公開の issue やフォーラムへの貼り付け用です。

• --llm claude-cli と --llm ollama は、すべてを既に管理しているアカウントとマシン内に留めます。

• プロンプトインジェクション対策：トランスクリプトには信頼できないテキスト（ツール結果の Web ページ、貼り付けられた README など）が頻繁に埋め込まれます。トランスクリプトを消費するすべてのプロンプト、ハンドオフの前文、ブリーフ注入ラッパーは、そのコンテンツをデータであり指示ではないと位置付けます — テストで固定されています。緩和策であり証明ではありません。パーサー自体は何も実行しません。

設定（任意）

常に使うデフォルトを ~/.config/claude-handoff/config.json に置きます（CLI フラグが常に優先。CLAUDE_HANDOFF_CONFIG でパスを上書き）：

{ "llm": "claude-cli", "fit": "32k", "include_tools": true }

許可されるキー：llm、model、fit、output、include_tools、include_sidechains、max_chars、anonymize、focus。セキュリティスイッチ（no_redact）は意図的に設定不可です — 編集の弱体化は明示的な実行ごとの選択でなければなりません。壊れた設定は警告して無視され、致命的にはなりません。

環境変数

claude-cli は変数を必要としません — インストール済みの Claude Code CLI をシェルアウトし、Pro/Max プランに請求されます（ログインするには claude を一度実行）。

MCP サーバー

あらゆる MCP クライアント（Claude Desktop、Claude Code など）がハンドオフを直接取得できます：

claude mcp add claude-handoff -- claude-handoff --mcp

ツール：list_sessions（このマシンにあるもの）と handoff（名前/プロジェクト/パスでセッションのドキュメントを構築。共有可能なバージョンには anonymize を渡します）。デフォルトで決定的 — MCP クライアントが LLM 要約をトリガーできるのは、--allow-llm 付きでサーバーを起動した場合のみです。

トラブルシューティング

pip install 後に claude-handoff: command not found pip はスクリプトを PATH にない可能性のあるユーザー bin ディレクトリに置きます。pipx install claude-handoff または brew を使用してください — どちらも PATH を管理します — または ~/.local/bin（Linux）/ ~/Library/Python/3.x/bin（macOS）を PATH に追加してください。

「~/.claude/projects の下にセッションが見つかりません」 Claude Code を実行したことがないマシン（またはユーザー）であるか、ストアが別の場所にあります — CLAUDE_HOME をそこに向けてください。プロジェクトフォルダ内ではツールはそのプロジェクトにスコープされます。すべてを検索するには --any を渡してください。

間違ったセッションが選択された 「最新」はほぼ空のスタブをスキップしますが、それでも単に最新のファイルです。-i（ピッカー）、--name "タイトルの一部"、または --grep "言ったこと" を使用してください。

--llm claude-cli が失敗する、または認証を求められる claude を一度実行してログインします（/login）。これは Claude Code セッションの内側から呼び出した場合でも機能します — 継承された CLAUDE* 環境変数は除去されるため、ネストされた CLI は新しいものと同じように認証されます。

"Set ANTHROPIC_API_KEY … to use --llm claude" API プロバイダーは環境にキーが必要です — 上の表を参照してください。キーがまったくない場合は --llm claude-cli（サブスクリプション）または --llm ollama（ローカル）を使用してください。

--fit が --llm / --max-chars と組み合わせるのを拒否する --fit は決定的な出力を単独でサイズ調整します。自分で入力していない場合、設定ファイルで fit が設定されている可能性があります — 明示的な --max-chars を削除して上書きするか、キーを削除してください。

ブリーフの注入が「このブリーフより新しいセッションが存在します」と警告する これは鮮度スタンプの仕事です: chf --brief --llm claude-cli を実行して再蒸留してください（キャッシュされる — 新しいセッションのみが課金されます）。[事実の部分は、SessionEnd フックがインストールされていれば自動的に更新されます]

何かが静かに何もしなかった？ 耐性設計のパス（壊れた JSONL 行、読み取れないファイル、キャッシュの問題）は実行を決してクラッシュさせません — --debug（または CLAUDE_HANDOFF_DEBUG=1）を追加して、何がスキップされたか、その理由を正確に確認してください。フックは常に stderr にエラーを報告し、それでも exit 0 を返します。

Windows で文字化け PYTHONUTF8=1 を設定してください（CI はこの方法で全体のスイートを実行します）。

全フラグリファレンス

ロードマップ

• Gemini エクスポートを入力として（Google Takeout は HTML のみを配布 — 実際のレッドアクション済みエクスポートをビルドに持参）

• セッションチェーン: /compact で継続されたセッションを自動検出し、系統のマージを提案（--follow）

PR 歓迎。

他との比較

このスペースは空ではありません — 断片化されています。状況に合ったツールを選んでください:

• エクスポーター — claude-conversation-extractor、claude-code-log、claude-code-transcripts、claude-to-markdown — トランスクリプトを読みやすい Markdown/HTML に変換、ツールノイズ含む、ハンドオフフレーミングなし。

• クロス CL Iセッションムーバー — cli-continues（npm i -g continues）は 16 のコーディング CLI のネイティブセッションストア（Claude Code 含む）を読み取り、別のターミナルツールにコンテキストドキュメントを注入します。Claude Code → Codex/Cursor/Gemini CLI に最適; ただし Web チャットを対象にできず、LLM サマリーは行わず、Node 22.5+ が必要です。

• セッション内ハンドオフスキル/プラグイン — thepushkarp/handoff、claude-session-handoff、claude-code-handoff — セッション終了前に実行するのを覚えている場合に最適; モデルはセッションのコンテキストを使ってサマリーを書き、出力は次の Claude セッションを対象にします。

• ブラウザ拡張機能 — Handoff、LLM Context Bridge、ContextSwitch — ChatGPT/Claude/Gemini 間でWeb チャットを転送; Claude Code セッションは見ることができません。

claude-handoff はこの地図の事後、どこにでも貼り付けられるコーナーです: JSONL を事後に処理します — 古いセッション、クラッシュしたセッション、使用制限に達したセッション — 事前に何もインストールする必要がなく、デフォルトでゼロトークン、要求すれば実際のサマリーを書くことができ（--llm）、ブラウザやスマホの claude.ai、ChatGPT、Gemini を含むどの受け取りモデルでも拾えるドキュメントを生成します。そして --brief を使えば、その履歴を恒久的なプロジェクトメモリに変える唯一のものです。

開発

git clone https://github.com/Vasilispapg/claude-handoff && cd claude-handoff
python3 -m unittest discover -s tests -v      # the whole suite (no deps needed)
python3 -m claude_handoff tests/fixtures/agent_session.jsonl -o -   # smoke run
python3 scripts/build_single.py --check       # single-file build is fresh
uvx ruff check claude_handoff scripts tests   # lint (config in pyproject)

ランタイムコードは claude_handoff/ パッケージにあります; single/claude_handoff.py は生成されています — パッケージを変更したら python3 scripts/build_single.py で再ビルドしてください（CI は古いと失敗します）。新しいパーサー動作は tests/fixtures/ のレッドアクション済みフィクスチャから始まります — CONTRIBUTING.md と AGENTS.md を参照してください（人間と AI の両方の貢献者向けの指示と不変条件）。

詳細

docs/GUIDE.md — claude-handoff のある一日: ウォークスルー、--brief の仕組みをステップバイステップ、正直なコスト表、チートシート · INDEX.md — ファイルマップ · docs/DEVELOPMENT.md — アーキテクチャ、JSONL スキーマノート、設計上の決定 · AGENTS.md — AI コーディングエージェント向け貢献者ガイド · CONTRIBUTING.md · CHANGELOG.md

ライセンス

MIT

mcp-name: io.github.Vasilispapg/claude-handoff