Agent Usage Tracker

---

name: agent-usage-tracker description: Track AI agent token usage, model costs, and budget thresholds with a TypeScript and SQLite workflow. Use when the user wants to instrument agent runs, calculate token spend, enforce per-session or time-window budgets, or analyze usage by model, session, or time range.

---

Agent Usage Tracker

Use this skill when you need local token accounting for AI agents.

What it provides

Real-time token usage persistence in SQLite

Cost calculation based on per-model pricing

Budget thresholds with persisted warning and blocking states

Usage statistics grouped by time window, session, or model

Files to use

src/UsageTracker.ts: ingestion, storage, and reporting

src/CostCalculator.ts: pricing catalog and cost math

src/BudgetManager.ts: budget policy evaluation

examples/basic-usage.ts: end-to-end usage example

tests/: reference behavior for tracking, budgeting, and aggregation

Recommended workflow

1. Instantiate UsageTracker with a SQLite path or :memory: for tests. 2. Register model pricing with CostCalculator. 3. Record each agent interaction with prompt tokens, completion tokens, session id, and timestamp. 4. Save reusable budgets with BudgetManager.setBudget, then call evaluateBudget before or after new work to warn or stop when a limit is exceeded. 5. Use UsageTracker.getUsageSummary or getTimeSeries for reporting.

Integration notes

Store token counts at the moment the provider returns usage metadata.

Keep model ids normalized. Pricing lookup is exact by model id.

Use metadata for provider-specific fields such as request id or tool name.

For sliding-window budgets, query usage by startTime and endTime before dispatching new work.

Output expectations

This skill ships as a local Node.js package with tests and examples. Extend CostCalculator if your provider pricing changes.