pai-cost-tracker

name	pai-cost-tracker
description	Hourly Claude subscription usage guardrail. Reads PAI canonical usage cache (~/.claude/MEMORY/STATE/usage-cache.json) for 5h/7d window percentages. Voice-alert via pai-pulse if threshold exceeded. Use when user says usage, cost, am I burning too much, take a break, claude limit, rate limit.

pai-cost-tracker skill

Why this exists

Two goals: catch API-vs-subscription cost leaks early (PAI's CostTracker.ts ledger shows a real $498 invoice from processes silently billing API), and wellness — voice-alert when the 5h/7d subscription window is near its limit so the user stops.

When to use

User intent:

• "usage" → snapshot current 5h/7d %
• "am I close to limit" → threshold check
• "cost this month" → API spend from admin key (if available)
• Automated hourly cron — see cron/README.md (Hermes jobs.json registration)

Data sources

Source	What	Path
PAI usage cache	5h/7d %, native rate_limits	~/.claude/MEMORY/STATE/usage-cache.json
PAI CostTracker ledger	Historical snapshots	~/.claude/PAI/MEMORY/OBSERVABILITY/anthropic-cost.jsonl
Hermes own model usage	Multi-provider tokens consumed	~/.hermes/state.db (sqlite, table TBD)
Anthropic admin API	API spend $ this month	deferred to v0.2 — ANTHROPIC_ADMIN_API_KEY path not yet implemented

Thresholds (default)

Canonical source: tools/cost_check.py DEFAULT_THRESHOLDS. Values below are read from that dict.

Window	Warn	Alert (voice)	Block
5h Claude	60%	80%	95%
7d Claude	70%	85%	95%
7d Opus-specific	—	90%	—
7d Sonnet-specific	—	90%	—
Monthly extra_usage credits	—	70%	—
API spend (admin key)	—	deferred to v0.2	—

Configurable in ~/.hermes/config.yaml under pai_hermes.cost_thresholds:.

Algorithm

1. Run cost_check.py --cache "$PAI_USAGE_CACHE" --voice (see Invoking below). It reads five_hour/seven_day/…utilization, classifies against thresholds, and prints only when action is needed (breach or stale cache).
2. Quiet hours (22:00–07:00 local): still read + snapshot, but drop --voice/pai-pulse; log the suppression.
3. Non-empty stdout → invoke pai-pulse with the composed message. At Block level, tag priority + push to Telegram via the Hermes gateway.
4. Append the snapshot to ~/.hermes/state/pai-cost-snapshots.jsonl (audit trail) every run.
5. Return the JSON summary for in-context display.

Output

{ "schema": "pai-hermes.cost.v1", "ts": "2026-05-16T15:00:00Z",
  "five_hour_pct": 78, "seven_day_pct": 52, "opus_7d_pct": 65, "sonnet_7d_pct": 30,
  "extra_credits_used_pct": 12, "alerts_triggered": ["five_hour"], "block_triggered": [],
  "next_reset_5h": "2026-05-16T18:00:00Z" }

Voice alert composition

Templates per trigger, sent via pai-pulse (ElevenLabs TTS). API-spend voice alert deferred to v0.2.

• five_hour: "5 hour Claude window at {pct}%. Consider taking a break."
• seven_day: "Weekly Claude limit at {pct}%. Reset in {hours} hours."
• extra_credits: "Extra credits at {pct}% of monthly limit. ${used} of ${limit}."

Cron entry

Register via Hermes — see cron/README.md. Job is stored in ~/.hermes/cron/jobs.json:

{ "name": "pai-cost-tracker", "schedule": { "kind": "cron", "expr": "0 * * * *" }, "skill": "pai-cost-tracker" }

Coordination with omc skill

Pre-flight gate: if 5h window ≥80% (ALERT, per tools/cost_check.py DEFAULT_THRESHOLDS), omc skill refuses ralph/team/autopilot/ultrawork until reset or user passes --force.

Invoking cost_check.py

cost_check.py lives at the pai-hermes checkout root, not inside the installed skill dir — running it relative to the skill cwd fails. install.sh records the checkout path as PAI_HERMES_ROOT in $HERMES_HOME/pai-hermes.env. Source that env file, then call by absolute path:

set -a; . "${HERMES_HOME:-$HOME/.hermes}/pai-hermes.env"; set +a
/usr/bin/python3 "$PAI_HERMES_ROOT/tools/cost_check.py" \
  --cache "${PAI_USAGE_CACHE:-$HOME/.claude/MEMORY/STATE/usage-cache.json}" --voice

execute_code is the preferred execution path for cron invocations.

Caveats

• Schema/path drift — some canonical installs place 5h/7d fields at the top level (no rate_limits wrapper) and store the cache at ~/.claude/MEMORY/STATE/usage-cache.json rather than the older ~/.claude/PAI/MEMORY/STATE/ path. cost_check.py handles both schemas; pass --cache explicitly if it reports 0% across the board. See references/usage-cache-schema.md.
• Empty --voice stdout is the success path — all metrics within threshold. Only non-empty output signals an alert.
• Stale cache is itself alertable — --voice emits a staleness warning when cache mtime >15 min old. Common; alert on it, do not treat as broken state.
• 5h/7d % from the Claude OAuth API rate-limits aggressively (5 reads before 429). Hourly cron is safe.
• Hermes own model usage (z.ai/GLM, OpenRouter, etc.) is NOT in Claude windows — separate spend.
• Quiet hours (22:00–07:00): run the read + snapshot but suppress --voice/pai-pulse; log the decision.
• Audit: append metric JSON to ~/.hermes/state/pai-cost-snapshots.jsonl every run for a continuous burn-rate record.
• If terminal returns pending_approval / pattern_key: "tirith:unknown", re-run via execute_code with subprocess.run([...], timeout=15) instead of retrying terminal unchanged.

References

• references/usage-cache-schema.md — canonical cache path, current top-level schema, and stale-cache alert semantics.
• references/tool-path.md — why cost_check.py lives outside the installed skill dir and how to invoke it via $PAI_HERMES_ROOT.

Cost

ZERO AI cost. File reads + JSON parsing + optional Pulse POST.

Triggers in Hermes natural language

• "how much have I used" → snapshot
• "am I close to limit" → threshold check, summarize
• "what's my burn rate" → trend from snapshots jsonl
• Pre-flight before omc ralph etc. — silent unless threshold hit