Cache TTL

Cache TTL

TL;DR: The cache stays warm for 1 hour on a subscription plan and 5 minutes on API-key or credit billing (D). The widget works out which TTL applies from the last cache write. If you've been idle longer than the TTL, the cache is cold.

TTL values (D)

Billing	TTL
Subscription plan, within plan usage	1 hour
API key, cloud, usage credits, or plan credits used up mid-session	5 minutes

The TTL can change mid-session, for example when plan credits run out.

How the widget learns the TTL (H)

Only cache writes show the TTL:

• c1 > 0 → wrote to the 1-hour cache → TTL is 1h
• c5 > 0 → wrote to the 5-minute cache → TTL is 5m
• A cache hit (read only) has c1 = c5 = 0, so it gives no TTL evidence.

The rules, in claude-usage.2m.py:

1. Go through the session's requests in time order.
2. On every main-thread write, record the TTL.
3. On a read-only request, keep the last recorded TTL.
4. On a model switch, forget the TTL. A different model has a different cache.
5. Skip subagent requests. They share the session id but have their own model and cache.
6. If there is no evidence yet, assume 5m.

Is the cache warm right now?

idle_min = now − time of last main-thread request
ttl_min  = 60 if TTL is 1h else 5
cold_now = idle_min > ttl_min

Example: 1h TTL, last message 12 minutes ago → 12 < 60 → warm. The same idle time on a 5m TTL → 12 > 5 → cold.

Don't confuse with "cold restart"

Signal	Question	Used for
cold_now	Is the cache warm now?	Live menu advice
cold	Was the last request a cache-miss rewrite?	Counting past overspend

See Cold-cache detection.

---

Next: Cold-cache detection →