claude-webcache

claude-webcache

Claude Code 向けの、セッションをまたいで永続化される WebFetch キャッシュです。キャッシュからの読み込みは約 0.07ms で、再取得より桁違いに高速です。

Claude Code 組み込みのキャッシュは、1 つのセッション内で 15 分間有効です。新しいセッションを開始するたび、最初から再取得します。claude-webcache はローカルの SQLite データベースに結果をセッションをまたいで保存するため、キャッシュヒットは瞬時で、ネットワークコストはかかりません。

Session 1  →  WebFetch("docs.example.com")  →  fetched, auto-cached ✓
Session 2  →  cached_fetch("docs.example.com")  →  instant hit, no network call
Session 7  →  cached_fetch("docs.example.com")  →  still instant, unlimited TTL

v0.1.5 以降： PostToolUse フックにより、すべての WebFetch が自動的に保存されます。設定は不要です。

インストール

claude plugin marketplace add theYahia/claude-webcache && claude plugin install claude-webcache@theyahia

Claude Code CLI・デスクトップ（Mac/Windows）・VS Code 拡張機能・JetBrains プラグインで動作します。どこでも同じコマンドを使えます。

これで完了です。以後、すべての WebFetch が自動的にキャッシュされます。

必要に応じて、使用パターンを ~/.claude/CLAUDE.md に追加すると、取得する前にキャッシュも確認できます（同じ URL を再利用する場合、WebFetch の呼び出し自体を省略できます）。

プラグイン TUI が動作しませんか？ /plugin install がサードパーティーのソースを「source type not supported」として拒否する、Claude Code の未解決のバグ（#41653）があります。上記の CLI コマンドを使ってください。TUI を介さず、問題なく動作します。

代替手段（マーケットプレイスを使わない場合）：

git clone https://github.com/theYahia/claude-webcache && claude --plugin-dir ./claude-webcache/plugin

オプション 2 — npm グローバルインストール

npm i -g @theyahia/claude-webcache

Node.js 22.5 以降が必要です（組み込みの node:sqlite を使用するため、ネイティブ依存関係もインストール手順もありません）。

その後、~/.claude/settings.json に登録します（パスは npm root -g の出力に置き換えてください）。

{
  "mcpServers": {
    "claude-webcache": {
      "command": "node",
      "args": ["/path/from/npm-root-g/claude-webcache/scripts/mcp-server.cjs"]
    }
  },
  "hooks": {
    "SessionStart": [
      {
        "matcher": "startup|clear|compact",
        "hooks": [
          { "type": "command", "command": "node /path/from/npm-root-g/claude-webcache/scripts/hook-stats.cjs" }
        ]
      }
    ]
  }
}

オプション 3 — クローン（コントリビューター向け）

CONTRIBUTING.md を参照してください。

使用パターン（任意 — 取得前にキャッシュを確認する場合）

v0.1.5 以降、すべての WebFetch が自動的にキャッシュされます。 以下のパターンは任意です。~/.claude/CLAUDE.md に追加すると、WebFetch を実行する前にキャッシュも確認できます。同じ URL を再利用する場合、WebFetch の呼び出し自体を省略できます。

自動読み込み（v0.5 以降）：操作は不要です。 PreToolUse フックが、すべての WebFetch／WebSearch の前にキャッシュを確認します。ヒットした場合はキャッシュ済みのコピーを返し、ネットワークアクセスを省略します。ミスした場合は通常どおり呼び出しを実行し、PostToolUse フックが結果を保存します。今後どのセッションでも同じ URL と同じプロンプト（または同じ検索クエリ）を使うと、瞬時にヒットし、ネットワークコストはかかりません。

必要に応じて、手動での検索も引き続き利用できます。cached_fetch(url, prompt)（または cached_search(query)）を呼び出すと、キャッシュ済みのテキストが返されます。存在しない場合は [CACHE_MISS] … が返されます。WEBCACHE_AUTOREAD=0 で自動読み込みを無効にできます。

⚠ セキュリティ — 認証済み URL

キャッシュは、レスポンスとともに URL を ~/.webcache/cache.db に保存します。デフォルトでは、claude-webcache は書き込み前に、保存する URL から明らかな認証情報を取り除きます（user:pass@host や、token、api_key、apikey、access_token、auth、secret、password、key、signature などの名前を持つクエリパラメーター）。

これは表示レベルでのマスキングであり、キー単位のものではありません。 キャッシュキーは元の URL のハッシュ値を使うため、同じ認証済み URL を再取得するとキャッシュにヒットします。より厳格なトレードオフが必要な場合は、次の設定を使用してください。

export WEBCACHE_STRICT_REDACT=1

WEBCACHE_STRICT_REDACT=1 を設定すると、キャッシュキーもマスキング済み URL から計算されます。そのため、?token=A と ?token=B だけが異なるエンドポイントは、1 つのスロットに衝突します。パススルー認証（コンテンツが同一）には安全ですが、ユーザーごとに異なるエンドポイントでは安全ではありません（異なるユーザー同士でキャッシュデータが共有されます）。

結論： URL に埋め込んだトークンよりも、ヘッダーベースの認証（Authorization: ヘッダー）を優先してください。~/.webcache/cache.db を Git にコミットしないでください。

名前空間

1台のマシンを複数のプロジェクトで共有していますか？プロジェクトごとにキャッシュを分離できます。

WEBCACHE_NAMESPACE=gosdelo  claude    # cache writes/reads scoped to ns "gosdelo"
WEBCACHE_NAMESPACE=qsearch  claude    # separate ns, no cross-contamination

デフォルトの名前空間は空文字列 "" です（v0.3 の動作と同じく、キャッシュを共有します）。CLI で名前空間ごとの状態を確認・管理できます：claude-webcache namespaces、claude-webcache --namespace gosdelo stats。

ツール（MCP）

ツール	引数	戻り値
cached_fetch	url、prompt	キャッシュされたテキスト、または [CACHE_MISS] <url>
cached_search	query	キャッシュされた WebSearch の結果、または [CACHE_MISS] <query>（websearch 名前空間、短い TTL）
cache_store	url、prompt、output	stored
cache_stats	global?	{ namespace, total, hits, misses, hit_rate, last, db_size_bytes, evicted, oversize_skipped, last_hook_error_at, top_urls, ... }
cache_list	limit?、offset?、global?	最近の URL（新しいものから順）
cache_invalidate	url	{ deleted: N } — 現在の名前空間で、その URL のすべてのエントリーを削除します
cache_clear	older_than_days?、confirm?	{ deleted: N } — 経過日数による部分削除、または confirm:"YES" による全削除
cache_warm	entries: [{url,prompt}] または urls[]+prompt	{ hits, misses, invalid } — 1回の呼び出しで一括事前チェックします
cache_refresh	url、prompt	[CACHE_MISS] <url> — 無効化し、再取得を促します

CLI

npm パッケージには、臨時の確認に使える claude-webcache バイナリと、ローカル Web ダッシュボードが含まれています。

claude-webcache stats                            # JSON stats
claude-webcache stats --by-domain                # per-domain breakdown
claude-webcache list 20                          # 20 most-recent URLs
claude-webcache list 50 --offset 100             # pagination
claude-webcache invalidate https://news.com/123  # drop one URL
claude-webcache refresh https://news.com/123 --prompt "extract title"   # invalidate one (url,prompt) pair
claude-webcache warm urls.txt --prompt "extract" # bulk pre-flight check
claude-webcache clear --older-than-days 30       # partial wipe
claude-webcache clear --confirm YES              # full wipe (requires explicit confirm)
claude-webcache clear-logs                       # truncate ~/.webcache/hook.log
claude-webcache namespaces                       # list all namespaces present
claude-webcache export --out cache.json --all    # export metadata
claude-webcache dashboard                        # open http://localhost:37778
claude-webcache --namespace gosdelo stats        # scope command to namespace

ダッシュボードでは、ヒット数の多い URL、ドメイン（平均ヒット数／最終取得日時／エントリー数を含む）、検索可能でページ分割された全件リストを表示します。リストにはワンクリックで実行できる無効化ボタンと更新ボタンがあります。標準ライブラリのみで動作し、追加の依存関係は不要です。

設定（環境変数）

変数	デフォルト	効果
WEBCACHE_TTL_DAYS	無制限	グローバル TTL（日数）。0 または未設定の場合は無制限です。
WEBCACHE_MAX_SIZE_MB	無制限	このサイズを超えると、次回の書き込み時に、last_hit_at が古いエントリーの約 20% を LRU 方式で削除します（100 回の書き込みごとにデバウンス）。
WEBCACHE_DOMAIN_TTL	なし	ドメインごとの TTL を指定する JSON：{"news.com":1,"reuters.com":1,"arxiv.org":0}。日数を指定します。0 は無制限です。サブドメインにもサフィックス一致で適用されます。一致した場合はグローバル TTL より優先されます。
WEBCACHE_NAMESPACE	""（共有）	プロジェクトごとにキャッシュを分離します。異なる名前空間のエントリーは互いに参照できません。
WEBCACHE_MAX_OUTPUT_MB	10	N MB を超える WebFetch レスポンスを拒否します。統計には oversize_skipped カウンターと last_oversize_url が記録されます。
WEBCACHE_COMPRESS	オフ	1 にすると、4 KB 以上のレスポンスを gzip で圧縮します。TEXT 列には base64 として保存されます。既存の非圧縮行も問題なく読み込めます（BC）。
WEBCACHE_STRICT_REDACT	オフ	1 にすると、キャッシュキーに秘匿化した URL を使用します。トークンの値に関係なく、エンドポイントごとに衝突します。上記のセキュリティを参照してください。
WEBCACHE_QUIET	オフ	1 にすると、フックの stderr 出力を抑制します（~/.webcache/hook.log へのファイルログは引き続き書き込まれます）。
WEBCACHE_DEBUG	オフ	1 にすると、自動キャッシュフックの詳細なトレースを有効にします。
WEBCACHE_SEARCH_TTL_HOURS	6	キャッシュされた WebSearch 結果（websearch 名前空間）の TTL です。検索順位は変動するため、デフォルトでは短く設定されています。0 にすると期限切れになりません。
WEBCACHE_AUTOREAD	オン	0 にすると、PreToolUse の自動読み込みフックを無効にします（キャッシュへの書き込みは PostToolUse 経由で引き続き行われます。cached_fetch／cached_search で手動で読み込みます）。

SessionStart フック

新しいセッションの開始時に、キャッシュがあることを Claude に知らせる一行が挿入されます。

webcache [ns=gosdelo] 142 pages cached, 87% hit rate, last fetch 3h ago

キャッシュが空の場合は出力されません。デフォルトの名前空間を使用している場合、[ns=...] は省略されます。

ストレージ

~/.webcache/cache.db にある SQLite（WAL モード、synchronous=NORMAL、busy_timeout=5000）。 キャッシュキー = SHA256(namespace + "|" + canonical(url) + "|" + prompt)。デフォルトの TTL：無制限（N 日後に期限切れにするには WEBCACHE_TTL_DAYS=N を設定します）。

URL の正規化（v0.4 以降）：ホスト名を小文字に変換し、デフォルトポート（:80／:443）とフラグメントを取り除き、クエリパラメーターをアルファベット順に並べ替えます。そのため、https://EXAMPLE.com/p?b=2&a=1#frag と https://example.com/p?a=1&b=2 は同じキャッシュキーになります。URL の書式の違いによるキャッシュミスは発生しません。

フィールド	型
key	TEXT PRIMARY KEY
url	TEXT（秘匿化済み）
prompt_hash	TEXT
output	TEXT（compressed=1 の場合は gzip+base64）
cached_at	INTEGER（エポックからのミリ秒）
hit_count	INTEGER
last_hit_at	INTEGER
namespace	TEXT（デフォルトは ""）
compressed	INTEGER（0/1）

WAL と 5 秒の busy_timeout により同時実行に安全です。複数の Claude Code セッションから同時に読み書きしても、SQLITE_BUSY エラーは発生しません。

制限事項

• キャッシュキーにはプロンプトが含まれます。ヒット率を最大化するには、プロンプトを統一してください。
• 出力は WebFetch が返す内容（すでに要約済み）です。再処理は行いません。
• セマンティック検索には対応していません。完全一致する (namespace, canonical_url, prompt) のみが対象です。

ベンチマーク

データが格納された DB（N=10000 件、各出力 1KB）での単一プロセスのレイテンシーを、npm run bench で測定：

操作	p50	p95	p99	ops/sec
write	0.09ms	0.15ms	2.66ms	5,800
read_hit	0.07ms	0.12ms	0.23ms	7,600
read_miss	0.04ms	0.07ms	0.13ms	17,600
list_50	0.11ms	0.16ms	0.53ms	7,400

ストレージのオーバーヘッド：ペイロードが 1 KB の場合、エントリーごとに約 2 KB（キー + インデックス + WAL + 新しい v0.4 の列）。テキスト主体のレスポンスで WEBCACHE_COMPRESS=1 を設定すると、3～7 倍の削減が見込めます。

ネットワーク経由の WebFetch には通常 1～5 秒かかります。キャッシュヒットは約 15,000～70,000 倍高速です。お使いのハードウェアで再現するには、npm run bench を実行してください。測定方法と、実行ごとに保存される結果のメタデータ（CPU、RAM、OS、コミット）については、bench/README.md を参照してください。

関連項目

• claude-mem — セッションをまたいで保持される永続メモリ（claude-webcache を補完します。メモリとウェブキャッシュの違いです）
• WWmcp — 非西洋圏の API 向け MCP サーバー 46 件のカタログ

ライセンス

MIT — LICENSE を参照してください。

---

WWmcp の一部 · Telegram: @vhodvai