claude-webcache

Claude Code用のセッション間WebFetchキャッシュ。

Claude Codeに組み込まれている WebFetch は、単一セッション内で15分間結果をキャッシュします。claude-webcache はこれをセッションをまたいで無期限（TTL 7日、設定可能）に拡張します。

Open new session  ->  your past fetches are still there.
Cache hit         ->  instant.
Cache miss        ->  same as built-in WebFetch.

なぜこれが必要か

セッションをまたいで同じURL（ドキュメント、APIリファレンス、調査ページなど）を再フェッチするたびに、毎回フルフェッチのコストがかかります。15分間のセッション内キャッシュは、次のスプリントが始まる前に期限切れになってしまいます。claude-webcache はフェッチ結果を保持するため、2回目のセッションではキャッシュがヒットします。

インストール

オプション1 -- Claude Codeプラグイン（推奨）

ターミナルで以下の1行を実行します：

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

次に、~/.claude/CLAUDE.md に使用パターンを追加します（使用パターンを参照）。

💡 なぜTUIの /plugin install ではなくCLIサブコマンドなのか？ 現在のTUIフローはClaude Codeの remoteMarketplaceClient バックエンドを経由しますが、これにはサードパーティのプラグインソースをすべて拒否するサーバー側のバグがあり、Failed to install: This plugin uses a source type your Claude Code version does not support. というエラーが発生します。anthropics/claude-code#41653 および関連する約20件のオープンなIssueを参照してください。上記のCLIサブコマンドはローカルで NativeMarketplaceReader を使用するため、影響を受けません。

フォールバック（CLIサブコマンドでもセットアップが失敗する場合）：

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

これにより、マーケットプレイスのパイプラインを完全にバイパスします。

オプション2 -- npm global

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 を参照してください。

使用パターン

~/.claude/CLAUDE.md に追加して、Claudeがキャッシュ経由でWebフェッチを行うようにします：

## WebFetch caching (claude-webcache)

Before calling WebFetch, call `cached_fetch(url, prompt)` first.
- If it returns text -> use that, do NOT call WebFetch.
- If it returns `[CACHE_MISS] <url>` -> call WebFetch as normal, then call `cache_store(url, prompt, output)` with the result.

以上です。今後のセッションで同じURL + 同じプロンプトを使用すれば、即座にキャッシュがヒットします。

ツール (MCP)

ストレージ

~/.webcache/cache.db にSQLiteを使用（WALモード、同時実行セーフ）。キャッシュキー = SHA256(url + "|" + prompt)。

SessionStartフック

新しいセッションごとに、フックが1行の統計情報を挿入します：

webcache: 142 pages cached, 38 hits, last fetch 3h ago

キャッシュが空の場合は挿入をスキップします。

TTL

デフォルトは7日間です。期限切れのエントリは、同じキーが次に読み取られたときに削除されます。src/cache.js を読み込んで purgeExpired() を呼び出すことで、手動でパージを実行できます。

制限事項

• キャッシュキーにはプロンプトが含まれるため、同じURLでもプロンプトが異なれば別々のエントリになります。ヒット率を最大化するために、一貫したプロンプト（例：常に "extract title and main content"）を選択してください。

• 出力はWebFetchが返すもの（モデルによって既に要約済み）そのままです。キャッシュ側で再処理は行いません。

• セマンティック検索や埋め込み機能はありません。完全な (url, prompt) 一致のみです。

ライセンス

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