/compactコマンドの内部動作を完全解説：Claude Codeの会話圧縮で87%のトークン削減

Claude Codeを使っていると、コンテキストウィンドウがいっぱいになって「会話を圧縮してください」と促されることがあります。その時に実行する/compactコマンドは、内部でどのような処理を行っているのでしょうか？ある開発者がmitmproxyを使ってHTTPSトラフィックを傍受し、実際に何が起きているかを詳細に調査しました。結果、21メッセージが3メッセージに、14,280トークンが1,820トークンに圧縮され、約87%の削減を達成していることが明らかになりました。

この記事のポイント
Claude Codeの会話保存の仕組み
/compactが実行する処理
mitmproxyを使った実験の方法
実測データ：驚くべき圧縮効率
圧縮のトレードオフ
実践してみよう
知っておくと便利なTips
まとめ

この記事のポイント

Claude Codeの会話は~/.claude/projects/にJSONLファイルとして保存される
/compactは履歴を削除せず、「compact_boundary」マーカーを追加するだけ
APIへの送信時に21メッセージ→3メッセージ、87%のトークン削減を実現
圧縮後は要約+直近のメッセージのみがサーバーに送信される

Claude Codeの会話保存の仕組み

まず基本的な仕組みを理解しましょう。Claude Codeは会話履歴をローカルの~/.claude/projects/ディレクトリにJSONL形式で保存しています。各メッセージは以下の構造を持ちます：UUID（一意識別子）、type（”human”、”assistant”、または”system”）、message（ロールとコンテンツ）、timestamp（ISO 8601形式）、sessionId（会話の識別子）。

重要なのは、あなたが送信するすべてのメッセージは、完全な会話履歴と共にAnthropicのサーバーに送信されるということです。つまり、会話が長くなればなるほど、各リクエストのペイロードサイズも増加し、トークン消費も増えていきます。

/compactが実行する処理

/compactを実行しても、ローカルの会話履歴は削除されません。代わりに、subtype: "compact_boundary"というシステムドキュメントが追加され、これがチェックポイントとして機能します。この境界にはcompactMetadataが含まれ、トリガータイプと圧縮前のトークン数が記録されます。

この設計により、ローカルには完全な会話履歴が保持されつつ、APIリクエスト時には圧縮後の要約のみが送信されるようになります。いわば「見えない区切り線」を引いているようなものです。

mitmproxyを使った実験の方法

著者は以下のセットアップで実験を行いました。まずmitmproxy、jq、tiktokenをインストールし、mitmproxyでSSL証明書を生成します。新しいディレクトリを作成し、mitmproxyを起動してapi.anthropic.comへのリクエストをフィルタリング。別のターミナルでClaude Codeをプロキシ経由で起動し、10個の段階的なプロンプトで会話履歴を構築しました。

この方法により、/compact実行前後のAPIリクエストのペイロードを正確に比較できました。

実測データ：驚くべき圧縮効率

実験の結果は非常に印象的でした。

指標	圧縮前	圧縮後	削減率
メッセージ数	21	3	86%
トークン数	14,280	1,820	87.3%
バイト数	41.8 KB	6.2 KB	85.1%

21のメッセージがたった3つに圧縮されているのがわかります。圧縮後のペイロードには、システムプロンプト、会話の要約、そして直近のメッセージのみが含まれています。

圧縮のトレードオフ

しかし、この圧縮にはトレードオフがあります。「要約は何が構築されたかを捉えますが、実装の詳細は失われます」と著者は指摘しています。具体的なコードスニペット、詳細なエラーメッセージ、段階的な思考プロセスなどは、要約によって抽象化されてしまいます。

これは実際の作業で問題になることがあります。例えば、「さっき書いたコードを少し修正して」と言っても、圧縮後はそのコードの詳細がコンテキストから失われている可能性があります。重要な実装の詳細を保持したい場合は、圧縮のタイミングを慎重に選ぶ必要があります。

実践してみよう

自分でも同様の実験を試すことができます。

# 必要なツールのインストール（macOS）
brew install mitmproxy
brew install jq
pip install tiktoken

# mitmproxyを起動（証明書生成のため）
mitmproxy
# qを押して終了、証明書は~/.mitmproxy/に生成される

# 実験用ディレクトリを作成
mkdir ~/compact-experiment && cd ~/compact-experiment

# 1つ目のターミナルでmitmproxyを起動
mitmproxy
# fを押してフィルタを設定: api.anthropic.com

# 2つ目のターミナルでClaude Codeをプロキシ経由で起動
# （詳細な設定は元記事を参照）

mitmproxyでリクエストを選択してEnterを押すと詳細が表示され、実際のAPIペイロードを確認できます。圧縮前後でどのようにデータが変化するか、自分の目で確かめてみてください。

知っておくと便利なTips

自動圧縮のタイミング: Claude Codeはコンテキストが閾値に達すると自動的に圧縮を提案します。ただし、重要な作業の途中では手動でタイミングを制御した方が良い場合もあります。
会話履歴の確認: ~/.claude/projects/ディレクトリを直接確認することで、過去のすべての会話履歴にアクセスできます。JSONLファイルなのでjqコマンドで整形して読むことができます。
コンテキスト使用量の監視: /contextコマンドで現在のコンテキスト使用状況を確認できます。圧縮が必要かどうかの判断に役立ちます。
圧縮前の重要情報の保存: 圧縮後に失われる可能性のある重要な情報（具体的なコード、設定値など）は、圧縮前にファイルに保存しておくと安心です。