claude-pace 0.8.0 → 0.8.2

package/README.md

@@ -1,17 +1,39 @@
 # Claude Pace
 
-A lightweight status line for Claude Code that tracks your 5-hour and 7-day rate limit usage in real time. Pure Bash + jq, single file, zero npm.
+A lightweight Claude Code status line and rate limit tracker that shows your 5-hour and 7-day quota usage in real time. Pure Bash + jq, single file, zero npm.
 
-Most statuslines show "you used 60%." That number means nothing without context. 60% with 30 minutes left? Fine, the window resets soon. 60% with 4 hours left? You're about to hit the wall. claude-pace compares your burn rate to the time remaining and shows the delta: are you ahead of pace or behind?
+If you are searching for a Claude Code statusline, a Claude Code quota monitor, or a Claude Code usage tracker, claude-pace is built for that narrow job. It shows not only how much quota you have used, but whether your current burn rate is sustainable before the window resets.
 
 ![claude-pace statusline demo](.github/claude-pace-demo.gif)
 
+## TL;DR
+
+- Claude Code status line with `5h` and `7d` quota usage, reset countdowns, and pace delta
+- Pace-aware rate limit tracking, `⇡15%` means overspending, `⇣15%` means headroom
+- Pure Bash + jq, single file, no Node.js runtime and no lockfile churn
+- Install as a Claude Code plugin, with `npx`, or as a single script
+
+Most statuslines show "you used 60%." That number means nothing without context. 60% with 30 minutes left? Fine, the window resets soon. 60% with 4 hours left? You are about to hit the wall. claude-pace compares your burn rate to the time remaining and shows the delta.
+
 - **⇣15%** green = you've used 15% less than expected. Headroom. Keep going.
 - **⇡15%** red = you're burning 15% faster than sustainable. Slow down.
 - **15%** / **20%** = used in the 5h and 7d windows. **3h** = resets in 3 hours.
 - Top line: model, effort, project `(branch)`, `3f +24 -7` = git diff stats
 
-## Install
+Claude Code supports custom status lines through its `statusLine` setting and `/statusline` workflow in the official docs:
+
+- [Customize your status line](https://code.claude.com/docs/en/statusline)
+- [Claude Code settings](https://docs.anthropic.com/en/docs/claude-code/settings)
+
+## Table of Contents
+
+- [Install This Claude Code Statusline](#install-this-claude-code-statusline)
+- [Upgrade](#upgrade)
+- [Claude Code Statusline Comparison](#claude-code-statusline-comparison)
+- [How Claude Pace Tracks Quota](#how-claude-pace-tracks-quota)
+- [Claude Code Statusline FAQ](#claude-code-statusline-faq)
+
+## Install This Claude Code Statusline
 
 Requires `jq`.
 
@@ -65,7 +87,7 @@ To remove: delete the `statusLine` block from `~/.claude/settings.json`.
 
 Release notifications: Watch this repo → Custom → Releases.
 
-## How It Compares
+## Claude Code Statusline Comparison
 
 |  | claude-pace | [claude-hud](https://github.com/jarrodwatts/claude-hud) | [CCometixLine](https://github.com/Haleclipse/CCometixLine) | [ccstatusline](https://github.com/sirmalloc/ccstatusline) |
 |---|---|---|---|---|
@@ -79,21 +101,21 @@ Execution and memory measured on Apple Silicon, 300 runs, same stdin JSON.
 
 Need themes, powerline aesthetics, or TUI config? Try [ccstatusline](https://github.com/sirmalloc/ccstatusline). The entire source of claude-pace is [one file](claude-pace.sh). Read it.
 
-## Under the Hood
+## How Claude Pace Tracks Quota
 
 Claude Code polls the statusline every ~300ms:
 
 | Data | Source | Cache |
 |------|--------|-------|
 | Model, context, cost | stdin JSON (single `jq` call) | None needed |
-| Quota (5h, 7d, pace) | stdin `rate_limits` (CC >= 2.1.80) | None needed (real-time) |
+| Quota (5h, 7d, pace) | stdin `rate_limits`; fallback to last-known private cache when `rate_limits` is absent | Private cache root, accepted only before cached reset |
 | Git branch + diff | `git` commands | Private cache dir, 5s TTL |
 
-Usage tracking requires Claude Code `2.1.80+`, where `rate_limits` is available in statusline stdin. claude-pace does not call the Anthropic Usage API.
+Best experience is on Claude Code `2.1.80+`, where `rate_limits` is available in statusline stdin. When a later statusline run omits `rate_limits`, claude-pace can reuse the last known stdin quota snapshot from its private cache until either cached reset time expires.
 
 Cache files live in a private per-user directory (`$XDG_RUNTIME_DIR/claude-pace` or `~/.cache/claude-pace`, mode 700). All cache reads are validated before use. No files are ever written to shared `/tmp`.
 
-## FAQ
+## Claude Code Statusline FAQ
 
 **Does it need Node.js?**
 No. Only `jq` (available via `brew install jq` or your package manager). No npm, no node_modules, no lock files.
@@ -102,7 +124,7 @@ No. Only `jq` (available via `brew install jq` or your package manager). No npm,
 claude-pace compares your current usage percentage to the fraction of time elapsed in each window (5-hour and 7-day). If you've used 40% of your quota but only 30% of the time has passed, the pace delta shows ⇡10% (red, burning too fast). If you've used 30% with 40% of time elapsed, it shows ⇣10% (green, headroom).
 
 **Does it make network calls?**
-No. All displayed quota data comes from stdin. If `rate_limits` is missing, claude-pace shows `--` for quota and can still show the local session cost.
+No. Quota data comes from stdin `rate_limits` on Claude Code `2.1.80+`. If a later statusline run omits `rate_limits`, claude-pace can reuse the last known stdin quota snapshot from its private cache as long as that snapshot's reset times are still in the future. Otherwise it falls back to `--` and may still show the local session cost.
 
 **Can I inspect the source?**
 The entire tool is [one Bash file](claude-pace.sh). Read it before you install it.

package/claude-pace.sh

@@ -65,6 +65,17 @@ _write_cache_record() {
     printf '%s\n' "$*"
   ) >"$tmp" && mv "$tmp" "$path"
 }
+# Avoids rewriting the quota cache when the live snapshot is unchanged.
+_write_quota_snapshot_if_changed() {
+  local path="$1" u5="$2" u7="$3" r5="$4" r7="$5"
+  if [ -f "$path" ] && [ ! -L "$path" ] && [ -r "$path" ] && _load_cache_record_file "$path"; then
+    [[ "${CACHE_FIELDS[0]:-}" == "$u5" ]] &&
+      [[ "${CACHE_FIELDS[1]:-}" == "$u7" ]] &&
+      [[ "${CACHE_FIELDS[2]:-}" == "$r5" ]] &&
+      [[ "${CACHE_FIELDS[3]:-}" == "$r7" ]] && return 0
+  fi
+  _write_cache_record "$path" "$u5" "$u7" "$r5" "$r7"
+}
 # Computes remaining whole minutes until a future epoch. Missing or expired
 # timestamps return an empty string so callers can skip countdown formatting.
 _minutes_until() {
@@ -74,6 +85,16 @@ _minutes_until() {
   ((mins < 0)) && mins=0
   printf '%s\n' "$mins"
 }
+# Valid quota snapshots must contain integer usage values and future reset
+# epochs for both windows. Partial or expired snapshots never enter the cache.
+_valid_quota_snapshot() {
+  local u5="$1" u7="$2" r5="$3" r7="$4"
+  [[ "$u5" =~ ^[0-9]+$ ]] || return 1
+  [[ "$u7" =~ ^[0-9]+$ ]] || return 1
+  [[ "$r5" =~ ^[0-9]+$ ]] || return 1
+  [[ "$r7" =~ ^[0-9]+$ ]] || return 1
+  ((r5 > NOW && r7 > NOW))
+}
 # Collects live Git metadata for DIR. On non-repos, leaves defaults in place
 # and returns non-zero so callers can decide whether to cache the empty result.
 _collect_git_info() {
@@ -101,6 +122,8 @@ for _BASE in "${XDG_RUNTIME_DIR:-}" "${HOME}/.cache"; do
   CACHE_OK=1
   break
 done
+QC=""
+[[ "$CACHE_OK" == "1" ]] && QC="${_CD}/claude-sl-quota"
 # Returns true (exit 0) when file is missing or older than $2 seconds.
 _stale() { [ ! -f "$1" ] || [ $((NOW - $(stat -f%m "$1" 2>/dev/null || stat -c%Y "$1" 2>/dev/null || echo 0))) -gt "$2" ]; }
 
@@ -198,12 +221,30 @@ fi
 SHOW_COST=0
 if [[ "$HAS_RL" == "1" ]]; then
   # Stdin path: real-time, no network. U5/U7 already set by jq read above.
-  # Guard: resets_at=0 means field missing, leave RM empty so _pace/_rc skip it
+  # Guard: resets_at=0 means field missing, leave RM empty so _usage skips it.
   RM5=$(_minutes_until "$R5")
   RM7=$(_minutes_until "$R7")
+  if [[ -n "$QC" ]] && _valid_quota_snapshot "$U5" "$U7" "$R5" "$R7"; then
+    _write_quota_snapshot_if_changed "$QC" "$U5" "$U7" "$R5" "$R7" || true
+  fi
 else
   U5="--" U7="--" RM5="" RM7=""
   SHOW_COST=1
+  if [[ -n "$QC" ]] && _load_cache_record_file "$QC"; then
+    _CU5=${CACHE_FIELDS[0]:-}
+    _CU7=${CACHE_FIELDS[1]:-}
+    _CR5=${CACHE_FIELDS[2]:-}
+    _CR7=${CACHE_FIELDS[3]:-}
+    if _valid_quota_snapshot "$_CU5" "$_CU7" "$_CR5" "$_CR7"; then
+      U5="$_CU5"
+      U7="$_CU7"
+      R5="$_CR5"
+      R7="$_CR7"
+      RM5=$(_minutes_until "$R5")
+      RM7=$(_minutes_until "$R7")
+      SHOW_COST=0
+    fi
+  fi
 fi
 
 # Combined usage formatter: used% [pace delta] (countdown)

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "claude-pace",
-  "version": "0.8.0",
-  "description": "A statusline for Claude Code. Pure Bash + jq, single file.",
+  "version": "0.8.2",
+  "description": "Claude Code statusline and rate limit tracker. Pure Bash + jq, single file.",
   "bin": {
     "claude-pace": "cli.js"
   },
@@ -15,11 +15,18 @@
   },
   "keywords": [
     "claude-code",
+    "claude-code-statusline",
+    "claude-code-plugin",
     "statusline",
+    "status-line",
+    "rate-limit-tracker",
     "quota",
+    "quota-tracker",
     "usage",
+    "usage-monitor",
     "pace-tracking",
-    "bash"
+    "bash",
+    "jq"
   ],
   "license": "MIT",
   "repository": {