usage

Overview ¶

Persistent cache for the rolling 30-day usage dashboard — the aggregate report AND the per-file incremental index, both on disk. This is the safe redesign:

• Persisted (disk) = ~/.rmote/agent/usage_month.json. Holds the version, lastRefreshMs, and a per-file index: (path, mtime, size) → {that file's full-history (date,model) contribution}. A few hundred KB → low MB (paths + day×model cells dominate). Loaded on daemon start.
• In-memory = the same index + the running aggregate, rebuilt from the persisted index on load. GET serves the finalized (windowed) report instantly.

Cold/full scans happen ONLY when the cache file is missing, corrupt, the schema version mismatches, or (rare) the aggregate is nil. A normal `brm` loads the index, so the first Refresh after restart is already incremental (~ms) — no multi-second scan. Unchanged files are skipped; changed/new files are re-parsed and their contribution REPLACED (subtract old, merge new); deleted/aged-out files (>30d mtime, never seen by the walk) are dropped.

The window is ROLLING 30 days (not calendar month), so there is no month-rollover cold reset — the window slides and finalize() re-applies it each refresh. Per-file contributions are the file's FULL history (window-independent), so subtract/merge stay exact as the window moves.

Safety vs. the old saga: this stores per-file (date,model)-bucketed contributions (one tiny struct per cell), never the 175k per-line records (~80MB), and loads once at startup with none of the eviction/reload churn that spiked to 300MB. No polling, no background tick — refresh only on explicit POST.

On-demand rolling 30-day usage — types + accumulator. The wire shape (monthReport) matches the old UsageReport Codable so the restored dashboard decodes it unchanged. Scanning/caching lives in month_cache.go; this file holds the pure data structures shared by the cache and the per-file parsers.

The window is a rolling 30 days (not calendar month), so the dashboard's Daily/Weekly/Monthly tabs can all slice one scan: Daily=today, Weekly=last 7d, Monthly=last 30d. byDay + byDayModel are keyed by ABSOLUTE date ("2006-01-02") — day-of-month keying would collide across months.

Per-file contributions are parsed as the file's FULL history (no since filter) so a contribution is window-independent: subtract/merge stay exact as the 30-day window slides, and finalize() applies the window. The walk bounds the index by skipping files with mtime older than the window (they carry no in-window turns).

Memory-safety invariant (the lesson from the dashboard's idle-memory saga): the persisted index holds one tiny (date,model)-bucketed struct per transcript file — never the ~175k per-line records that cost ~80MB, and never the 20MB blob that spiked to 300MB. No polling, no background tick.

Per-agent transcript parsers for the on-demand month view (month_total.go). Each parser streams one transcript file and folds its in-month tokens into a shared *monthAccum. None of them retain per-record state — the accum's buckets are the only thing that survives past a line loop.

Field names + paths reused verbatim from the deleted report.go / codex_usage.go / grok_usage.go (verified against on-host transcripts):

Claude ~/.claude/projects/**/*.jsonl
  type=="assistant", message.usage.{input,output,cache_read,cache_creation}_tokens
  message.model, timestamp (RFC3339Nano)

Codex  ~/.codex/sessions/**/*.jsonl   (ONE cumulative record per session)
  session_meta.payload.timestamp  → session date
  turn_context.payload.model      → model (last wins)
  event_msg payload.type=="token_count" → payload.info.total_token_usage
    {input_tokens, output_tokens, total_tokens(=in+out)}

Grok   ~/.grok/sessions/<cwd>/<uuid>/signals.json
  contextTokensUsed (context SNAPSHOT, not throughput) + primaryModelId
  dated by file mtime

Pi (earendil-works pi coding-agent) usage for the rolling 30-day dashboard. Each pi session is a JSONL tree at ~/.pi/agent/sessions/<dir>/<ISOts>_<uuid>.jsonl. Assistant messages carry a nested `message.usage` object:

{"type":"message","id":...,"timestamp":"2026-08-11T16:00:47.572Z",
 "message":{"role":"assistant","model":"glm-5.2",
           "usage":{"input":1612,"output":2269,"cacheRead":62336,
                    "cacheWrite":0,"reasoning":2047,"totalTokens":66217,
                    "cost":{...}}}}

totalTokens = input+output+cacheRead+cacheWrite (reasoning excluded — same convention codex uses for its reasoning tokens). The four buckets map onto the accum's input/output/cacheRead/cacheCreate (pi's cacheWrite = cache creation). cost is ignored: BYO-key providers report 0 and the daemon never prices. The line-level `timestamp` is ISO-8601 (the nested message.timestamp is epoch-ms; either resolves to the same day bucket — we use the line level for consistency with the Claude parser).