AGENTS.md

Guidance for coding agents working on Claude Usage Monthly Cap and Session Gauge in the claude-usage-cost project.

Project overview

This guide covers computeCapGauge and computeSessions in src/parser.ts plus their dashboard renderers. The extension estimates the current calendar-month API-equivalent value, overflow above included allowance, linear month-end projection, recent monthly history, and approximate rolling sessions from hourly buckets.

Primary source files

• src/parser.ts owns computeCapGauge and computeSessions.
• src/extension.ts applies includedMonthlyAllowanceUsd and softCapLinesUsd settings to the store.
• package.json declares cap-related settings.
• media/dashboard.js renders the gauge, monthly history, current session, and recent session bars.

Setup commands

npm install npm run compile npm run check-types npm run package npx esbuild src/selftest.ts --bundle --platform=node --format=cjs --outfile=out/selftest.js node out/selftest.js <transcript-dir>

Change rules

• Treat cap and session output as estimates, not official billing or remaining-limit truth.
• Compute overflow as max of zero and month value minus included allowance.
• Sort soft cap lines and ignore non-positive settings.
• Use a minimum elapsed-day denominator so early-month projection does not divide by zero.
• Reconstruct sessions from hourly buckets and keep the dashboard copy clear that this is approximate.

Testing

Cover zero usage, usage below allowance, usage above allowance, custom cap lines, several months of history, current active session, no active session, and session boundaries around the configured window length.

PR checklist

• Settings changes recompute cap data.
• Gauge handles empty or invalid cap lines.
• Dashboard labels remain estimate-safe.
• npm run check-types and npm run compile pass.