Llmcache

llmcache

Claude が昨日すでに理解したコードを、もう一度理解するために料金を払うのはやめましょう。

llmcache は、ソースコードに対する AI 生成の理解をキャッシュする MCP サーバーです。Claude は各ファイルを一度だけ読み込み、それ以降のすべてのセッションはキャッシュ済みの理解をもとに開始するため、トークンと費用を節約できます。

重要な理由

Claude Code はステートレス API を使用します。毎回のターンで、Claude が読み込んだすべてのファイルを含む会話履歴全体が、入力トークンとして再送されます。ターン 1 で読み込まれた 1,000 トークンのファイルには、セッションの残りのすべてのターンで、毎回 1,000 入力トークン分の料金がかかります。

llmcache は、その 1,000 トークンのファイルを 50 トークンの要約に置き換えます。一度だけではなく、すべてのターンで950 トークンを節約できます。

さらに、Claude は各ファイルを処理するために出力トークンも生成します。要約がキャッシュされていれば、Claude はその作業を完全に省略できます。出力トークンは入力トークンの 5 倍の料金がかかります。

Without llmcache:
  Turn 1: prompt + file.go (1,000 tokens)        > you pay for 1,000
  Turn 5: prompt + file.go still in history       > you pay for 1,000 again
  Turn 10: still carrying it                      > and again

With llmcache:
  Turn 1: prompt + summary (50 tokens)            > you pay for 50
  Turn 5: summary still in history                > you pay for 50
  Turn 10: still just 50 tokens                   > 95% smaller

前提条件

• Claude Code（サポートされている唯一のクライアント）
• Git（キャッシュの無効化に使用）
• 次のいずれか：
  • Anthropic API キー（ANTHROPIC_API_KEY）
  • Vertex AI API を有効にした GCP プロジェクトと gcloud auth application-default login

インストール

お使いのプラットフォーム用のバイナリをダウンロードします。

# macOS (Apple Silicon)
curl -L -o llmcache https://github.com/sp98/llmcache-site/releases/latest/download/llmcache-darwin-arm64

# macOS (Intel)
curl -L -o llmcache https://github.com/sp98/llmcache-site/releases/latest/download/llmcache-darwin-amd64

# Linux (x86_64)
curl -L -o llmcache https://github.com/sp98/llmcache-site/releases/latest/download/llmcache-linux-amd64

chmod +x llmcache
sudo mv llmcache /usr/local/bin/

仕組み

1. Claude Code は Read の代わりに、MCP 経由で understand_file を呼び出します
2. llmcache はキャッシュ済みの要約が存在し、まだ最新かどうかを確認します（git ハッシュが一致しているか）
3. キャッシュヒット：コンパクトな要約を返します（通常、ファイル全体より 90％以上小さいサイズです）
4. キャッシュミス：Claude Haiku を呼び出して要約を生成し、キャッシュしてから返します

ファイルの git ハッシュが変わると、要約は自動的に無効になります。

セットアップ

ローカルキャッシュは SQLite に保存されます。サーバーもライセンスキーも必要ありません。

1. MCP サーバーを追加する

claude mcp add --transport stdio llmcache -- llmcache mcp

Vertex AI を使用する場合は、リージョンを指定します。

claude mcp add \
  --env CLOUD_ML_REGION=us-east5 \
  --transport stdio llmcache -- llmcache mcp

2. Read フックを追加する

このフックにより、Claude はソースファイルを直接読み込む代わりに understand_file を使用するようになります。~/.claude/settings.json に追加します。

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Read",
        "hooks": [
          {
            "type": "command",
            "command": "F=$(cat | grep -o '\"file_path\":\"[^\"]*\"' | head -1 | cut -d'\"' -f4); B=${F##*/}; E=${F##*.}; case \"$B\" in Makefile|makefile|GNUmakefile) echo '{\"permissionDecision\":\"deny\",\"permissionDecisionReason\":\"Use understand_file from llmcache instead.\"}';; *) case \"$E\" in go|py|js|ts|tsx|jsx|rs|java|c|cpp|cc|h|hpp|rb|sh|proto|sql|md) echo '{\"permissionDecision\":\"deny\",\"permissionDecisionReason\":\"Use understand_file or understand_package from llmcache instead.\"}';; esac;; esac"
          }
        ]
      }
    ]
  }
}

3. CLAUDE.md の指示を追加する

~/.claude/CLAUDE.md に追記します。

MANDATORY: ALWAYS use understand_file or understand_package from the
llmcache MCP server instead of Read to understand source files.
Only use Read when you need exact line numbers for editing.

4. 確認する

Claude Code を再起動してプロジェクトで使用し、節約状況を確認します。

llmcache stats
llmcache stats --detail    # per-file breakdown
llmcache stats --monthly   # month-by-month

設定

環境変数または ~/.llmcache/config.yaml で任意の設定を行えます。

環境変数	デフォルト	説明
LLMCACHE_DB	~/.llmcache/data.db	SQLite データベースのパス
LLMCACHE_LOG_DIR	~/.llmcache/	ログディレクトリ
LLMCACHE_SUMMARY_MODEL	claude-haiku-4-5@20251001	要約の生成に使用するモデル

チームモード（近日公開）

ソロモードでは、各開発者が自分のキャッシュを一から構築します。開発者 A がファイルを理解しても、開発者 B は同じファイルを理解するために、依然として全トークン分の料金を支払います。チームモードでは要約が共有されるため、1 人の開発者が生成コストを負担すれば、他の開発者はすぐにキャッシュヒットを得られます。チームの開発者が増えるほど、キャッシュがより速く蓄積され、節約効果も大きくなります。

CLI コマンド

コマンド	説明
llmcache mcp	MCP サーバーを起動します（Claude Code によって自動的に起動されます）。
llmcache stats	キャッシュヒット数と、節約した入出力トークン数を表示します。ファイルごとの内訳には --detail、推移の確認には --monthly を使用します。
llmcache index <repo>	リポジトリのインデックスを事前に作成し、最初のセッションからキャッシュが利用できるようにします。並列ワーカーには -w 10、対象を絞り込むには --include "*.go" を使用します。
llmcache gc	古くなった要約を削除します。保持期間の設定には --max-age 720h、削除前の確認には --dry-run を使用します。

MCP ツール（Claude Code が自動的に使用）

ツール	説明
understand_file	ソースファイルのキャッシュ済みの要約を返します。ファイルが変更されている場合（git ハッシュが一致しない場合）は、新しい要約を生成します。未コミットの場合は、Claude に直接読み込むよう伝えます。
understand_package	ディレクトリ内のすべてのソースファイルを要約し、1 回の呼び出しで Claude にパッケージ全体の概要を提供します。
get_file_detail	ファイルから特定の関数または型を抽出します。Go ファイルには Go AST を使用し、それ以外のファイルにはパターン検索を使用します。
list_summaries	リポジトリ内のキャッシュ済みの要約をすべて、ヒット数と鮮度とともに一覧表示します。

バグとフィードバック

バグを見つけた場合や機能をリクエストする場合は、GitHub で issue を作成してください。