# Claude Code Cache TTL + Heartbeat Guide

> Public setup guide for a reversible Claude Code statusline TTL heuristic and a bounded heartbeat with a requested, not guaranteed, 50-minute cadence.

Canonical human pages:
- Chinese: https://claude-code-cache-heartbeat.pages.dev/
- English: https://claude-code-cache-heartbeat.pages.dev/en/

Agent-readable documents:
- Full guide: https://claude-code-cache-heartbeat.pages.dev/guide.md
- Execution contract: https://claude-code-cache-heartbeat.pages.dev/agent-setup.md
- Machine manifest: https://claude-code-cache-heartbeat.pages.dev/manifest.json
- Checksums: https://claude-code-cache-heartbeat.pages.dev/checksums.sha256

Installable assets:
- https://claude-code-cache-heartbeat.pages.dev/assets/ttl_statusline.py
- https://claude-code-cache-heartbeat.pages.dev/assets/statusline_mux.py
- https://claude-code-cache-heartbeat.pages.dev/assets/install_statusline.py
- https://claude-code-cache-heartbeat.pages.dev/assets/heartbeat-prompt.txt

Mandatory claim boundaries:
1. The statusline is a heuristic computed from the last assistant transcript record plus an assumed TTL. It is not a live cache-state API.
2. Official Anthropic API docs document a default 5-minute TTL and an extra-cost 1-hour option. They do not establish that every Claude Max or Claude Code session uses one hour.
3. Claims about Max defaulting to one hour or overage falling back to five minutes are contested and must not be presented as official fact.
4. `refreshInterval: 60` keeps time-based statusline data current while the session is idle.
5. `/loop 50m` is converted to cron and may be rounded; recurring tasks under hourly cadence can receive deterministic jitter up to half the interval, and busy turns delay execution. It cannot guarantee cache refresh before a one-hour TTL.
6. `/loop` is session-scoped. Count three observed no-progress checks rather than assuming 150 minutes. Recurring tasks fire once more and delete themselves seven days after creation.
7. Never overwrite the whole `~/.claude/settings.json`. Preserve existing statusline behavior, make a backup, verify, and retain rollback.
8. The mux re-executes only the pre-install trusted statusline command through `/bin/sh`; status JSON is stdin data, not command text. Verification must fail on mux-config hash drift or unsafe sensitive-file modes.

Recommended agent flow:
Read `agent-setup.md`, inspect current docs/settings, verify published checksums, run installer `--check`, explain the change, run `--apply` only with authorization, then run `--verify` and visually confirm the original statusline remains.