Claude Code · operational guide

让 cache 状态可见，
让后台任务不再悄悄结束。

一个可复制、可回滚、可由 agent 执行的配置：statusline 每 60 秒刷新 TTL 估算；长任务用 /loop 50m 请求周期检查，但实际 cadence 会受 cron rounding、jitter 与忙碌 turn 延迟影响。

开始配置交给 Agentllms.txt
CONTESTED

TTL 不是可观测真值

显示的是“最后一次 assistant 记录 + 假定 TTL”的 heuristic，不是 Claude Code cache API 的实时状态。

PRESERVE

不覆盖现有 statusline

安装器用 mux 保留原 command，写入前备份；卸载时恢复原配置。

SESSION-SCOPED

Heartbeat 不是 daemon

/loop 属于当前 Claude Code session；session 关闭时不会永久运行。

先分清三件事

它们相关，但不能混为一谈。

1. API cache TTL

Anthropic 官方 API 文档确认默认 5-minute TTL，也提供额外费用的 1-hour TTL。它没有证明每个 Claude Max / Claude Code 会话都固定使用 1 小时。

2. Statusline indicator

脚本从 transcript 尾部找最后一条 type: assistant，按可配置 TTL 计算到期时刻。这是估算，不应写成 confirmed cache state。

3. Background heartbeat

50m 是请求值，不是严格触发间隔。heartbeat 的可靠价值是兜底漏掉的完成通知；它不能保证在假定的 1h cache 到期前运行。

4. Overage claim

“Max 默认 1h、overage 降为 5m”缺少稳定公开规格；保留为 contested，不自动推断账户状态。

配置 statusline

推荐让 agent 读取 agent-setup.md 后执行。下面是人工路径。

1

下载发布资产

tmp="$(mktemp -d)"
cd "$tmp"
curl -fsSLO https://claude-code-cache-heartbeat.pages.dev/assets/ttl_statusline.py
curl -fsSLO https://claude-code-cache-heartbeat.pages.dev/assets/statusline_mux.py
curl -fsSLO https://claude-code-cache-heartbeat.pages.dev/assets/install_statusline.py
2

先做 dry check

python3 install_statusline.py --check

它只报告计划，不修改文件，也不输出现有 command 的正文。

3

应用并验证

python3 install_statusline.py --apply
python3 install_statusline.py --verify

安装器会备份 ~/.claude/settings.json，保留已有 statusline command，并设置 refreshInterval: 60。

不要直接复制一个新的完整 settings.json。只应修改 statusLine 对象；其它 hooks、permissions、plugins 和项目设置必须原样保留。
Executable trust boundary：mux 仅为保留原行为而通过 /bin/sh 重执行安装前已有 command；status JSON 只经 stdin 传入，不会插入 command。若旧 command 来源不可信，应停止安装。--verify 会检查 mux-config hash，并要求 settings、config、receipt、backup 使用 0600。

安装后的核心配置

{
  "statusLine": {
    "type": "command",
    "command": "python3 ~/.claude/claude-cache-heartbeat/statusline_mux.py",
    "refreshInterval": 60
  }
}

原来已有的 padding、hideVimModeIndicator 等键会保留。

改变估算 TTL

# 5-minute heuristic
export CLAUDE_CACHE_TTL_SECONDS=300

# 1-hour heuristic (default)
export CLAUDE_CACHE_TTL_SECONDS=3600

这只改变 statusline 的估算窗口，不会改变 Anthropic 服务端 cache 策略。

一键回滚

python3 install_statusline.py --uninstall

它如何工作

Claude Code status JSON (stdin) │ transcript_path ▼ statusline_mux.py ──→ original statusline command（保留） │ └──────────→ ttl_statusline.py │ tail read 256 KiB → 4 MiB │ parse JSONL; last type=assistant ▼ ttl~ HH:MM 或 TTL estimate expired
为什么一定要 refreshInterval: 60：官方 statusline 文档说明 event-driven updates 在 idle 时会安静下来。没有 timer，真正闲置时脚本不会重跑，显示会冻结。

约 50 分钟 heartbeat（请求值）

适用于预计运行较久、且你担心 completion notification 丢失的当前 session 任务。

/loop 50m Cache/heartbeat check-in. If a background task is running, do a quick non-blocking peek at its progress and report anything notable. Stop this loop once the task is done, or after 3 consecutive checks with no completion and no new progress. Otherwise reply "ok".
不是严格 50 分钟：Claude 会把 interval 转成 cron，并可能舍入到可表示的 cadence；不足 1 小时的 recurring task 还会加入最多半个 interval 的 deterministic jitter。Claude 忙于当前 turn 时也会继续延迟。因此它不能作为“1h TTL 到期前必定刷新”的保证。创建后必须读取确认消息，并列出 scheduled tasks 核对实际 schedule 与 job ID。

每次只做 non-blocking peek

读取进程状态或新增输出；不要把 heartbeat 本身变成长时间等待。

两个退出条件

任务完成立即停止；连续 3 次观察到的 heartbeat 无完成且无新进展也停止。由于 rounding、jitter 与 busy-turn 延迟，不能把它固定换算为 150 分钟。

生命周期：/loop 是 session-scoped；未过期任务可随 --resume/--continue 恢复，recurring task 创建 7 天后自动执行最后一次并删除。需要跨 session、重启或更长时间的任务应使用 durable scheduler。

验证清单

检查期望
python3 install_statusline.py --verifysettings、mux、TTL script、receipt 都 PASS
发送一条消息后观察出现灰色 ttl~ HH:MM
等待 60–120 秒时间型 segment 会由 timer 刷新，而不是仅在新消息后更新
短 TTL 测试临时设 CLAUDE_CACHE_TTL_SECONDS=60，过期后变成红色 block
原 statusline原模型、quota、git 等 segment 仍存在
创建 heartbeat 后确认 Claude 回报的实际 cron cadence 和 job ID；不要假定严格 50m
heartbeat任务完成或 3 次观察无进展后 loop 停止；recurring task 最多保留 7 天

给 Agent 的入口

llms.txt

发现入口、事实边界和资源目录。

guide.md

完整、可引用的 Markdown 指南。

agent-setup.md

可执行合同：inspect → check → backup → apply → verify → rollback。

manifest.json

机器可读的文件清单、版本和 claim status。

证据与限制

资料核对日期：2026-08-06。Claude Code 与服务端 cache 行为可能变化；执行 agent 应优先复查官方 docs。