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는 가져온 데이터를 유지하여 두 번째 세션에서 캐시를 적중하도록 합니다.

설치

옵션 1 -- Claude Code 플러그인 (권장)

터미널에서 한 줄로 실행:

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개의 관련 오픈 이슈를 참조하세요. 위의 CLI 하위 명령은 로컬에서 NativeMarketplaceReader를 사용하므로 영향을 받지 않습니다.

대체 방법 (설정에서 CLI 하위 명령조차 실패하는 경우):

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를 참조하세요.

사용 패턴

~/.claude/CLAUDE.md에 추가하여 Claude가 캐시를 통해 웹 가져오기를 수행하도록 합니다:

## 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 훅

새 세션이 시작될 때마다 훅이 한 줄의 통계를 삽입합니다:

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

캐시가 비어 있으면 삽입을 건너뜁니다.

TTL

기본값은 7일입니다. 만료된 항목은 동일한 키를 다음에 읽을 때 삭제됩니다. src/cache.js를 require하고 purgeExpired()를 호출하여 수동으로 삭제할 수 있습니다.

제한 사항

• 캐시 키에 프롬프트가 포함되므로 동일한 URL이라도 프롬프트가 다르면 별도의 항목으로 처리됩니다. 적중률을 극대화하려면 일관된 프롬프트(예: 항상 "extract title and main content")를 선택하세요.

• 출력은 WebFetch가 반환하는 그대로입니다(이미 모델에 의해 요약됨). 캐시는 이를 다시 처리하지 않습니다.

• 의미론적 검색이나 임베딩은 없습니다. 정확히 (url, prompt)가 일치해야 합니다.

라이선스

MIT -- LICENSE를 참조하세요.