costlens

# CostLens Turn JSON usage events into cost summaries, budget checks, and offline reports. ## When to use - You already have token usage events and need a quick spend summary. - You want a simple budget gate in local automation or CI. - You need an exportable JSON report without relying on a hosted billing dashboard. ## Commands ```bash node {baseDir}/bin/costlens.js monitor --events ./events.json --budget 10.00 --threshold 80 node {baseDir}/bin/costlens.js budget check --events ./events.json --budget 5.00 --format json node {baseDir}/bin/costlens.js report --events ./events.json --out ./reports/cost-report.json ``` ## Built-in default rates | Model | Input/1k | Output/1k | | --- | --- | --- | | gpt-4.1 | $0.01 | $0.03 | | gpt-4o-mini | $0.00015 | $0.0006 | | claude-3-5-sonnet | $0.003 | $0.015 | | default | $0.002 | $0.008 | Events can override the defaults with `inputCostPer1k` and `outputCostPer1k`. ## Event shape ```json [ { "model": "gpt-4.1", "promptTokens": 1500, "completionTokens": 800, "timestamp": "2026-02-26T10:00:00Z" } ] ``` ## Output - Total calls, total tokens, and total cost - Per-model breakdowns for calls, tokens, and cost - Per-day spend trends - Budget usage percentage and alert level (`ok`, `warning`, or `critical`) ## Boundaries - Pricing is based on built-in defaults plus per-event overrides. It is not a live pricing feed. - CostLens is optimized for offline JSON analysis, not streaming metering or invoice reconciliation.