51enuxu/cc-cache-playbook

This repository is a written playbook, not a piece of software you install. It documents lessons learned from running a self built chat gateway (for example a Telegram bot or web chat) that sits in front of Claude Code as a subscription based upstream, where usage is billed by request count rather than by the amount of text sent. The author explains how they cut the extra context sent on every turn from twenty to thirty thousand characters down to about two thousand, while raising their cache hit rate to ninety six percent. The core idea is that with a subscription plan, a long running conversation costs nothing extra to keep alive, but recalculating a conversation from scratch after a cache miss is expensive in wasted requests. So the advice is to keep sessions continuous whenever possible, and only start a fresh one when the conversation has genuinely broken off, saving heavy summarization for when a hard context limit is close. To decide whether a new message continues an old session, the playbook recommends hashing the content of the last user message as an anchor, rather than counting messages, since message counts can shift for unrelated reasons. For information that changes each turn, such as memory notes or status updates, it suggests sending only the parts that changed, marking removed sections clearly, and occasionally resending everything in full as a safety check. Content that never changes, like a persona's core instructions, is placed in a cached system prompt section instead of being repeated. The author also stresses logging context size, cache hit rate, and how many segments changed on every turn, since without this visibility a system can quietly get worse until it is obviously broken. A closing section on fallback summarization covers batch limits, backup upstream providers, and a check for a broken provider that returns an identical response no matter what is sent in.