claude-pace 0.7.3 → 0.8.1

package/README.md

@@ -1,17 +1,39 @@
 # Claude Pace
 
-Know your quota before you hit the wall. A statusline for Claude Code — single Bash 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 usage rate to the time remaining and shows the delta. No Node.js, no npm, no lock files. Single Bash file.
+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,36 +87,48 @@ 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 | Node.js/TypeScript statuslines | Rust/Go statuslines |
-|---|---|---|---|
-| Runtime | `jq` | Node.js 18+ / npm | Compiled binary |
-| Codebase | Single file | 1000+ lines + node_modules | Compiled, not inspectable |
-| Execution | ~10ms, 3% of refresh cycle | ~90ms, 30% of refresh cycle | ~5ms (est.) |
-| Memory | ~2 MB | ~57 MB | ~3 MB (est.) |
-| Failure modes | Read-only, worst case prints "Claude" | Runtime dependency, package manager | Generally stable |
-| Pace tracking | Usage rate vs time remaining | Trend-only or none | None |
+|  | claude-pace | [claude-hud](https://github.com/jarrodwatts/claude-hud) | [CCometixLine](https://github.com/Haleclipse/CCometixLine) | [ccstatusline](https://github.com/sirmalloc/ccstatusline) |
+|---|---|---|---|---|
+| Runtime | `jq` | Node.js 18+ / npm | Compiled (Rust) | Node.js / npm |
+| Codebase | Single Bash file | 1000+ lines + node_modules | Compiled binary | 1000+ lines + node_modules |
+| Rate limit tracking | 5h + 7d usage %, pace delta, reset countdown | Usage % | Usage % (planned) | None (formatting only) |
+| Execution | ~10ms | ~90ms | ~5ms | ~90ms |
+| Memory | ~2 MB | ~57 MB | ~3 MB | ~57 MB |
 
-Execution and memory measured on Apple Silicon, 300 runs, same stdin JSON. Rust/Go values are estimates.
+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 fallback | Anthropic Usage API (CC < 2.1.80) | Private cache dir, 300s TTL, async background refresh |
+| 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 |
 
-On Claude Code >= 2.1.80, usage data comes directly from stdin. No network calls. On older versions, it falls back to the Usage API in a background subshell so the statusline never blocks.
+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`.
 
+## 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.
+
+**How does pace tracking work?**
+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. 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.
+
 ## Also by the Author
 
 [**diffpane**](https://github.com/Astro-Han/diffpane) - Real-time TUI diff viewer for AI coding agents. See what Claude Code changes as it happens.
@@ -102,3 +136,5 @@ Cache files live in a private per-user directory (`$XDG_RUNTIME_DIR/claude-pace`
 ## License
 
 MIT
+
+*Last updated: 2026-04-13 · v0.8.0*

package/claude-pace.sh

@@ -74,6 +74,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 +111,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" ]; }
 
@@ -194,142 +206,34 @@ elif [[ "$IS_WT" == "1" ]]; then
   ((${#L1R} > 25)) && L1R="${L1R:0:25}…"
 fi
 
-# Usage data: prefer stdin rate_limits (CC >=2.1.80), fall back to API polling
+# Usage data: read stdin rate_limits when available, otherwise show session cost.
 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")
-  # Extra usage (XO/XU/XL) only available via API fallback; stdin lacks this data
-elif [[ "${CLAUDE_PACE_API_FALLBACK:-1}" != "0" ]]; then
-  # ── API fallback (disable via CLAUDE_PACE_API_FALLBACK=0) ──
-  UC="" UL=""
-  [[ "$CACHE_OK" == "1" ]] && {
-    UC="${_CD}/claude-sl-usage"
-    UL="${_CD}/claude-sl-usage.lock"
-  }
-
-  # ── _get_token: credential source priority ──
-  # Check in order: env var → macOS Keychain → credentials file → secret-tool (Linux).
-  _get_token() {
-    [ -n "$CLAUDE_CODE_OAUTH_TOKEN" ] && {
-      printf '%s' "$CLAUDE_CODE_OAUTH_TOKEN"
-      return
-    }
-    local b=""
-    command -v security >/dev/null &&
-      b=$(security find-generic-password -s "Claude Code-credentials" -w 2>/dev/null)
-    [ -z "$b" ] && [ -f ~/.claude/.credentials.json ] && b=$(<~/.claude/.credentials.json)
-    [ -z "$b" ] && command -v secret-tool >/dev/null &&
-      b=$(timeout 2 secret-tool lookup service "Claude Code-credentials" 2>/dev/null)
-    [ -n "$b" ] && jq -j '.claudeAiOauth.accessToken//empty' <<<"$b" 2>/dev/null
-  }
-
-  # ── _fetch_usage_api: direct API read into usage globals ──
-  # Used by both the cached background refresh path and the no-cache fallback.
-  _fetch_usage_api() {
-    local tk resp
-    # Command substitution strips trailing newlines. Append a sentinel byte only
-    # on success so malformed tokens with a trailing LF remain detectable here.
-    tk=$(_get_token && printf '\001') || return 1
-    [[ "$tk" == *$'\001' ]] || return 1
-    tk=${tk%$'\001'}
-    [ -n "$tk" ] || return 1
-    # OAuth bearer tokens must remain a single header line. Reject malformed
-    # credentials up front instead of letting curl parse injected CR/LF bytes.
-    case "$tk" in *$'\n'* | *$'\r'*) return 1 ;; esac
-    # Feed headers through process substitution so the bearer token stays out
-    # of curl argv while preserving literal bytes like quotes and backslashes.
-    resp=$(curl -s --max-time 3 \
-      -H @<(
-        printf 'Authorization: Bearer %s\n' "$tk"
-        printf '%s\n' 'anthropic-beta: oauth-2025-04-20'
-        printf '%s\n' 'Content-Type: application/json'
-      ) \
-      "https://api.anthropic.com/api/oauth/usage" 2>/dev/null)
-    IFS=$'\t' read -r U5 U7 XO XU XL RM5 RM7 < <(jq -r '
-      def rmins: if . and . != "" then (sub("\\.[0-9]+"; "") | sub("\\+00:00$"; "Z") | fromdateiso8601) - (now|floor) | ./60|floor | if .<0 then 0 else . end else null end;
-      [(.five_hour.utilization|floor),(.seven_day.utilization|floor),
-        (if .extra_usage.is_enabled then 1 else 0 end),
-        (.extra_usage.used_credits//0|floor),(.extra_usage.monthly_limit//0|floor),
-        (.five_hour.resets_at|rmins//""),(.seven_day.resets_at|rmins//"")]|@tsv' \
-      <<<"$resp" 2>/dev/null) || return 1
-  }
-
-  # ── _fetch_usage: background stale-while-revalidate fetch ──
-  # Runs in a subshell (&) so the main process returns immediately with cached data.
-  # On API failure, writes placeholder values once so the UI stays stable and
-  # avoids repeated refresh attempts until the cache TTL expires.
-  _fetch_usage() {
-    (
-      trap 'rm -f "$UL"' EXIT
-      if _fetch_usage_api; then
-        _write_cache_record "$UC" "$U5" "$U7" "$XO" "$XU" "$XL" "$RM5" "$RM7"
-      else
-        if [ ! -f "$UC" ] || [[ $(head -c2 "$UC") == -- ]]; then
-          _write_cache_record "$UC" "--" "--" "0" "0" "0" "" ""
-        fi
-      fi
-    ) &
-  }
-
-  # ── Lock mechanism (noclobber mutex) ──
-  # `set -o noclobber` makes `>` fail atomically if the file already exists,
-  # providing a lock without external tools. The stale-lock check (10s) ensures
-  # a crashed worker can't block refreshes indefinitely.
-  if [[ "$CACHE_OK" == "1" ]] && _stale "$UC" 300; then
-    if (
-      set -o noclobber
-      echo $$ >"$UL"
-    ) 2>/dev/null; then
-      _fetch_usage
-    elif [ -f "$UL" ] && _stale "$UL" 10; then
-      rm -f "$UL"
-      (
-        set -o noclobber
-        echo $$ >"$UL"
-      ) 2>/dev/null && _fetch_usage
-    fi
-  fi
-
-  # ── Read cache + drift correction ──
-  # The cache stores countdown minutes at write time; subtract elapsed seconds
-  # (in whole minutes) since the file was written to keep the countdown accurate
-  # between 300s refresh cycles without a network call.
-  U5="--" U7="--" XO=0 XU=0 XL=0 RM5="" RM7=""
-  if [[ "$CACHE_OK" == "1" ]]; then
-    if _load_cache_record_file "$UC"; then
-      U5=${CACHE_FIELDS[0]:---}
-      U7=${CACHE_FIELDS[1]:---}
-      XO=${CACHE_FIELDS[2]:-0}
-      XU=${CACHE_FIELDS[3]:-0}
-      XL=${CACHE_FIELDS[4]:-0}
-      RM5=${CACHE_FIELDS[5]:-}
-      RM7=${CACHE_FIELDS[6]:-}
-    fi
-    if [[ "$RM5" =~ ^[0-9]+$ ]] && [ -f "$UC" ]; then
-      _CA=$((NOW - $(stat -f%m "$UC" 2>/dev/null || stat -c%Y "$UC" 2>/dev/null || echo "$NOW")))
-      RM5=$((RM5 - _CA / 60))
-      ((RM5 < 0)) && RM5=0
-      [[ "$RM7" =~ ^[0-9]+$ ]] && {
-        RM7=$((RM7 - _CA / 60))
-        ((RM7 < 0)) && RM7=0
-      }
-    fi
-    [ ! -f "$UC" ] && SHOW_COST=1
-  elif ! _fetch_usage_api; then
-    SHOW_COST=1
+  if [[ -n "$QC" ]] && _valid_quota_snapshot "$U5" "$U7" "$R5" "$R7"; then
+    _write_cache_record "$QC" "$U5" "$U7" "$R5" "$R7" || true
   fi
-  U5=${U5%%.*} U7=${U7%%.*} XU=${XU%%.*} XL=${XL%%.*}
-  # Reject cache corruption or malformed API data before arithmetic formatting.
-  [[ "$XO" =~ ^[01]$ ]] || XO=0
-  [[ "$XU" =~ ^[0-9]+$ ]] || XU=0
-  [[ "$XL" =~ ^[0-9]+$ ]] || XL=0
-  # ── End API fallback ──
 else
-  # No stdin rate_limits and API fallback not enabled; show session cost only.
+  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)
@@ -359,8 +263,6 @@ _usage() {
 }
 
 # ── Output Assembly (symmetric single-pipe alignment) ──
-# Default XO/XU/XL for stdin path (extra usage only available via API fallback).
-: "${XO:=0}" "${XU:=0}" "${XL:=0}"
 
 # Build plain-text left sections for width measurement (no ANSI codes).
 L1_PLAIN="${MODEL} ${EF}"
@@ -379,10 +281,7 @@ L1="${C}${MODEL} ${EF}${N}${PAD1} ${D}|${N}  ${L1R}"
 
 # Line 2: bar pct% CL | 5h used% ...  7d used% ...
 L2="${BC}${BAR}${N} ${PCT}% ${CL}${PAD2} ${D}|${N}  5h $(_usage "$U5" "$RM5" 300)  7d $(_usage "$U7" "$RM7" 10080)"
-# Extra usage: only when enabled and has actual spending (API fallback only)
-[ "$XO" = 1 ] && ((XU > 0)) &&
-  printf -v _XS "  ${Y}\$%d.%02d${N}/\$%d.%02d" $((XU / 100)) $((XU % 100)) $((XL / 100)) $((XL % 100)) && L2+="$_XS"
-# Session cost: only when this run has no readable usage cache data.
+# Session cost: only when usage data is unavailable in stdin.
 if [[ "$SHOW_COST" == "1" ]]; then
   printf -v _CS "\$%.2f" "$COST" 2>/dev/null
   [[ "$_CS" != "\$0.00" ]] && L2+="  $_CS"

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "claude-pace",
-  "version": "0.7.3",
-  "description": "A statusline for Claude Code. Pure Bash + jq, single file.",
+  "version": "0.8.1",
+  "description": "Claude Code statusline and rate limit tracker. Pure Bash + jq, single file.",
   "bin": {
     "claude-pace": "cli.js"
   },
@@ -15,16 +15,23 @@
   },
   "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": {
     "type": "git",
-    "url": "https://github.com/Astro-Han/claude-pace"
+    "url": "git+https://github.com/Astro-Han/claude-pace.git"
   },
   "engines": {
     "node": ">=16"