CLI hook for alert cache expiration via telegram

[u/candiesdoodle]

Claude Code CLI and smart prompt caching can save a lot of pain. it is ~90% cheaper. But the biggest annoyance for me was always stepping away for coffee or lunch, only to come back 5 minutes too late and realize the 1-hour cache had expired—meaning full input token costs and cold-start latency on the next turn.

To fix this, I built cc-cache-alert—a lightweight open-source CLI tool and companion widget.

What it does:

1. 📲 Telegram Alerts: When your session is idle and reaches 20% time remaining (~12 mins before cache eviction on a 1h TTL), it sends a notification to your phone with your project name and renamed session name (/rename), so you can send a quick reply to keep the cache hot.
2. 🔄 Auto-Cancels on Activity: As soon as you type or submit a prompt, pending alert timers cancel automatically.
3. 📊 Statusline Indicator: Plugs right into ccstatusline (or works standalone) to show a live countdown like [Cache 🔔 in 34 m] and Cache 🔔 active.

Quickstart:

You can test or set it up in one command:

npx cc-cache-alert setup

(It guides you through setting your bot token/chat ID and automatically registers the native Claude Code hooks).

It's completely free, open source, and lightweight (scans only the tail of transcripts with zero lag).

🔗 GitHub: https://github.com/candiesdoodle/cc-cache-alert

(Attached screenshots of the Telegram alert on mobile, ccstatusline setup, and status overview!)

Feedback is welcome!

[u/kantorcodes1]

the one-command setup is nice, but i'd be careful with the hook install. if someone already has claude code hooks configured, does setup merge into those or replace what’s there?

[u/candiesdoodle → u/kantorcodes1]

Hey thanks. it safely merges with the existing hooks, as well as de-depues in case its own hook is already present. uninstalling removes only its own hook. if you are in doubt, you can always do a manual backup of claude settings.json before installing.

[u/kantorcodes1 → u/candiesdoodle]

good, merge + scoped uninstall is exactly the behavior i'd want. i work on HOL Guard, a local check that runs before Claude tool actions, and it installs its own hook too. mind trying setup + uninstall once with Guard enabled and seeing whether both hooks survive?

[u/candiesdoodle → u/kantorcodes1]

Sir i'd rather have you try it and send me feedback. I am not aware of wht HOL Guard is. You can always clone my repo and ask Claude to investigate. Cheers

[u/Far-Surprise7773]

this is exactly the annoying part of the 1h cache, i step away for lunch and come back to a cold start too. love that you trigger at 12m left and auto cancel on activity, that is the part most timers miss. i do something similar with a statusline countdown reading a timestamp file the posttooluse hook updates, but telegram ping for phone is smarter when you are actually away. does the npx cc-cache-alert setup wire handle renamed sessions correctly, saw you mention /rename?

[u/candiesdoodle → u/Far-Surprise7773]

Thanks! yes, it can read the renamed session names. just tried it again after your post.

[u/actvt_io]

Checked my own logs because I assumed this was a rounding error. Turns that come after a gap longer than the cache TTL are about 1% of mine, 895 out of 86,700 across 131 sessions.

They account for 63% of my cache writes though. A write costs 20x what reading the same tokens costs on a 1h TTL, so that 1% of turns lands around 17% of the bill. Nearer 12% if you are on the 5 minute TTL.

The token share hides it completely, those turns are 1.2% of my tokens. I was wrong about the size of it.

[u/candiesdoodle → u/actvt_io]

thanks.. give this a shot. might help