claude-pace 0.7.3 → 0.8.0

package/README.md

@@ -1,8 +1,8 @@
 # Claude Pace
 
-Know your quota before you hit the wall. A statusline for Claude Code — single Bash file, zero npm.
+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.
 
-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.
+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?
 
 ![claude-pace statusline demo](.github/claude-pace-demo.gif)
 
@@ -67,16 +67,15 @@ Release notifications: Watch this repo → Custom → Releases.
 
 ## How It Compares
 
-|  | 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.
 
@@ -88,13 +87,26 @@ Claude Code polls the statusline every ~300ms:
 |------|--------|-------|
 | 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 |
 | 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.
+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.
 
 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
+
+**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. 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.
+
+**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 +114,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

@@ -194,141 +194,15 @@ 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
   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
-  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
 fi
 
@@ -359,8 +233,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 +251,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,6 +1,6 @@
 {
   "name": "claude-pace",
-  "version": "0.7.3",
+  "version": "0.8.0",
   "description": "A statusline for Claude Code. Pure Bash + jq, single file.",
   "bin": {
     "claude-pace": "cli.js"
@@ -24,7 +24,7 @@
   "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"