CostLens

Calculate OpenClaw usage cost from offline event logs, apply budget thresholds, and export operator-facing reports.

Security Scan

CostLens is an internally consistent offline Node.js CLI for turning local JSON token-event logs into cost summaries and reports; its requested artifacts and behavior match the stated purpose.

Purpose & Capability

The skill declares a Node.js CLI that reads offline JSON event files, applies local pricing, checks budgets, and exports reports — and the code, README, SKILL.md, fixtures, and tests all implement exactly that. Required binaries (node) are appropriate and proportional.

Instruction Scope

SKILL.md instructs the agent to run the local Node CLI against a local events JSON file and optionally write a report file. The runtime instructions and the implemented code only read local files, compute aggregates, and write local outputs; they do not request additional system files, environment variables, or remote endpoints.

Install Mechanism

No install spec is provided (instruction-only + included source files). This minimizes install-time risk. The repository contains only local Node source, no downloads or external installers.

Credentials

The skill declares no required environment variables, credentials, or config paths, and the code does not read environment secrets. All data inputs are explicit file paths (events, out) supplied by the user.

Persistence & Privilege

The skill does not request always:true and does not modify other skills or global agent settings. It only writes report files to paths supplied by the user.

Assessment

This skill appears to do what it says: local offline analysis of JSON token events using Node.js. Before installing/running, ensure you have Node 18+ and run it only on event files you trust because it will read the events JSON and write report files to the paths you provide. It does not contact external services or require credentials. If you plan to let an autonomous agent invoke this skill, remember it can read any events file path you pass to it — avoid passing files that contain secrets or unrelated data.

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

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

[
  {
    "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.