v0.2.0 — 2026-06-25

Highlights

• Weekly limit monitoring (opt-in) — PAUSE at weekly_threshold_pause (default 98%) even when the 5-hour window is still low. Matches Desktop → Settings → Usage → "All models" weekly bar.
• Dual-threshold pause — either 5h ≥ 90% or weekly ≥ 98% triggers PAUSE; resume when both are clear. pause_reason in control.json (five_hour, weekly, both).
• Extra usage wallet in status, poll, doctor, and daemon logs (spend after 100%).
• Install path resilience — clearer errors when the clone path is stale; skill scripts find ~/.local/bin/usage-guard without relying on PATH.

Enable weekly monitoring

Add to ~/.usage-guard/config.json:

{
  "weekly_enabled": true,
  "weekly_threshold_pause": 98,
  "weekly_threshold_warn": 95
}

Re-arm after changing config (/usage-guard or usage-guard arm).

Reset proximity (v0.2.1): weekly_pause_within_hours: 5 — weekly PAUSE only when the weekly reset is within 5 hours. Omit for always-pause at 98%.

Since v0.1.6

v0.2.0

• Weekly limit monitoring (opt-in config)
• Extra usage wallet visibility
• Install path / repo-root fallback; actionable stale-path errors

v0.1.7 – v0.1.10

• telemetry_lost when usage API returns null 5h percent (3+ polls)
• One-time macOS notification when telemetry goes blind
• COOLDOWN wake skill aligned with Claude Code /loop / CronCreate
• COOLDOWN wording clarified for public skill users

Upgrade

cd usage-guard
git pull
./install.sh          # required — refreshes skill + CLI wrapper
usage-guard doctor    # expect version v0.2.0

git pull alone does not update the installed skill or CLI wrapper.

API note

Weekly data comes from OAuth seven_day — one aggregate number per account, not separate Sonnet/Opus weekly bars.

v0.1.6

Highlights

• usage-guard doctor shows your installed version and hints when a newer release exists
• How to upgrade: git pull && ./install.sh in your clone (pull alone does not update the skill)
• Broader fit: long Claude Code sessions / high window % — not tied to one model

Since v0.1.0

v0.1.6

• Update notice in doctor (24h cache; set USAGE_GUARD_NO_UPDATE_CHECK=1 to skip)
• README Updating section; __version__ synced to tags

v0.1.5

• Fix: checkpoint.sh writes to sitting_session_id after join.sh
• ScheduleWakeup COOLDOWN path; task_ignored when arming with task on live daemon

v0.1.4

• Local reset times; post-reset stale-percent guidance; checkpoint --quiet

v0.1.3

• last_reset_at, sleep_until, join.sh, multi-session support

v0.1.2

• Account-level usage docs; cooldown aligned to reset clock

v0.1.1

• First-poll wait; checkpoint.sh

Upgrade

cd usage-guard
git pull
./install.sh
usage-guard doctor

v0.1.0

proactive 5-hour usage guard for Claude Code on macOS.

Install
git clone https://github.com/shirley-xue-2025/usage-guard.git
cd usage-guard && ./install.sh
claude login # once, for usage reads
usage-guard doctor

Use: /usage-guard <task> in Desktop Code or CLI before long Fable/batch work.

Proactive pause near 90%, checkpoints on disk, /usage-guard resume after reset. Pairs well with claude-auto-retry if you still hit 100%.