| name | watch-limits |
| description | Use when you want a recurring monitor of your Claude subscription usage limits — weekly/5h burn rate, whether you'll blow the weekly cap before it resets, which idle session to compact, and ctx-wire token savings. Triggers: "am I going to hit my limit", "watch my usage", "burn rate", "which session to compact". |
watch-limits — recurring usage-limit watcher
Overview
Installs an activity-aware burn-rate projector and schedules a recurring status
watcher. The watcher reports, every ~30 min: weekly + 5h limit burn, a
compaction pick, and ctx-wire savings. Do not hand-roll the projection or
the schedule — this skill is the canonical setup; reinventing it produces
false alarms and duplicate jobs.
Prerequisites
cctop on PATH (cctop --json works) — per-session live stats.~/.claude/cctop/usage.json present and fresh (<1h). Written by a status-line
tap (cctop --capture-usage); if missing, tell the user to set up that tap
first — the watcher has no weekly data without it.ctx-wire (optional) for section 4. Skip that section if absent.
Setup flow
- Install the projector:
mkdir -p ~/.claude/cctop
cp "${CLAUDE_PLUGIN_ROOT}/skills/watch-limits/burn-proj.py" ~/.claude/cctop/burn-proj.py
- Guard against duplicates. List existing scheduled jobs first. If a
7,37 * * * * watcher reading usage.json already exists, STOP — offer to
replace it (delete the old one), never add a second. Duplicate watchers
double the noise and can clobber each other.
- Schedule the watcher. Use the prompt in
watcher-prompt.md (bundled
beside this file). Schedule it recurring at 7,37 * * * * (off the :00/:30
marks on purpose). If the host has no cron tool, run it as a /loop instead.
- Seed the ctx-wire delta baseline so the first tick shows a real interval:
printf '{"saved_tokens":%s,"ts":%s}\n' \
"$(ctx-wire gain --json | jq .saved_tokens)" "$(date +%s)" \
> ~/.claude/cctop/ctxwire-last.json 2>/dev/null || true
The projection (why not straight-line)
The 7-day window is FIXED, not rolling: it hard-resets at
seven_day.resets_at; window start = resets_at − 604800. burn-proj.py
prints two numbers:
- naive =
used / elapsed_fraction — worst case, assumes you burn every day
at your average-so-far rate. Self-heals as elapsed grows.
- profile_aware = discounts the hours you predictably don't burn — a sleep
window (02:00–09:00 ×0.05) and the weekend (Sat ×0.5, Sun ×0.1). The real
forecast — a hot evening or weekday start does NOT mean you'll blow the cap if
the hours ahead are predictably light (asleep or resting).
Lead with profile_aware; flag only when it exceeds 100%. Reporting a naive
evening/mid-week spike as "WILL BLOW" is the false alarm this skill exists to
prevent — the projection should bend down as the clock nears your sleep window.
Tune the sleep hours and weekend multipliers in burn-proj.py's mult() to
your own cadence (default active window 09:00–02:00).
Caveats
- Scheduled jobs are session-only on most hosts (die when the agent exits,
auto-expire in ~7 days). Re-run this skill after a restart.
durable:true is
often ignored — verify rather than assume.
- Cloud schedules can't see local
cctop/ctx-wire/usage.json, so this
watcher only works in a session with the binaries present.
Common mistakes
| Mistake | Fix |
|---|
| Redesigning the burn math inline | Use burn-proj.py — sleep/weekend discounting is the point |
| Scheduling a 2nd watcher | Check existing jobs first; replace, don't duplicate |
| Reporting naive % as the verdict | Lead with profile_aware; naive is the ceiling |
Sorting sessions on contextTokens raw | Treat null as 0 |
| Compacting a busy session | Only idle/waiting are safe targets |
