Token Usage Cost Report

Author: jovd83 | Version: 1.2.2 | License:

Use this skill when the user wants a trustworthy token-consumption or cost report for one or more agent sessions, tasks, or repositories.

What This Skill Does

This skill helps an agent:

• discover supported runtime evidence
• accept normalized usage bundles for unsupported runtimes
• validate pricing and usage inputs
• fetch official provider pricing when local coverage is missing
• generate auditable Markdown, HTML, and JSON reports
• generate repository dashboards when many report directories already exist

What This Skill Must Not Do

Do not:

• estimate token counts from transcript text alone
• use blog posts, screenshots, or memory-based prices
• silently remap an unknown model to a different exact pricing row
• claim exact cost when pricing dimensions remain unresolved
• treat host tools like VS Code as the billing source

When the user wants the story of how a result was built (the prompts, the model choices, a rough cost for a colleague), use the how-did-you-do-that skill instead. It estimates from transcripts and labels the figure as an estimate. This skill is for auditable figures.

Operating Model

Work in five stages:

1. Confirm scope and evidence type.
2. Validate or discover evidence.
3. Resolve pricing from official or validated local sources.
4. Generate the report artifacts.
5. Review the output and respond with grounded caveats.

1. Confirm Scope

Accept inputs such as:

• a single session file
• a session directory
• a date-scoped directory of sessions
• a manifest describing multiple sources
• a normalized usage bundle
• a repository reports directory for dashboard generation

Interpret complete task as a finished unit of work with a clear start and end in structured evidence.

If the user only provides transcript text or screenshots, refuse token and cost estimation and explain that structured usage evidence is required.

2. Identify The Evidence Mode

Use direct parsing only when the runtime is directly supported by the bundled parser.

Read runtime-support.md only when you need to decide whether a runtime is:

• directly supported
• normalization-only
• host-only
• unsupported

Use the normalized usage contract when trustworthy exports exist but a direct parser is not bundled.

3. Validate Inputs Before Reporting

Validate local pricing tables before use:

python scripts/validate_pricing_table.py path\to\pricing-table.json

Validate normalized usage bundles before use:

python scripts/validate_normalized_usage.py path\to\normalized-usage.json

Use the bundled examples and schemas when building inputs:

• normalized-usage.example.json
• normalized-usage.schema.json
• pricing-table.schema.json

4. Discover Evidence When Sources Are Not Exact

Run discovery first when the user names a timeframe or runtime but not exact files:

python scripts/token_usage_cost_report.py discover
python scripts/token_usage_cost_report.py discover --json

When the work targets Google Antigravity repositories, inventory evidence before full reporting:

python scripts/build_antigravity_evidence_inventory.py `
  --projects-root C:\projects\antigravity_prj `
  --output-dir C:\reports\antigravity-evidence-inventory

Treat Antigravity evidence as heuristic unless exact token fields are exposed.

5. Resolve Pricing Safely

Prefer:

• official provider pricing pages
• validated local pricing tables copied from official sources

When local coverage is missing, fetch official pricing with the bundled helper:

python scripts/fetch_official_pricing.py `
  --provider openai `
  --provider anthropic `
  --provider google `
  --output path\to\official-pricing.json

Read pricing-sources.md only when you need official source rules or billing caveats.

6. Choose The Right Reporting Path

Direct source reporting

python scripts/token_usage_cost_report.py report `
  --source C:\Users\me\.codex\sessions\2026\03\27 `
  --pricing C:\reports\pricing\official-pricing.json `
  --output-dir C:\reports\token-usage `
  --format both

Claude Code reporting (Anthropic models)

Claude Code stores per-turn usage at %USERPROFILE%\.claude\projects\<encoded-cwd>\<session>.jsonl. Convert one or more sessions/projects to a normalized bundle, then report:

python scripts/parse_claude_code_session.py `
  $env:USERPROFILE\.claude\projects\c--projects-myrepo `
  --runtime-host claude-code-cli `
  --output C:\reports\claude\bundle.json

python scripts/validate_normalized_usage.py C:\reports\claude\bundle.json

python scripts/token_usage_cost_report.py report `
  --source C:\reports\claude\bundle.json `
  --pricing C:\reports\pricing\official-pricing.json `
  --output-dir C:\reports\claude\report `
  --format both

Anthropic pricing rows produced by fetch_official_pricing.py cover Opus 4.5–4.7, Sonnet 4–4.6, and Haiku 4.5, including the four billing dimensions: input_per_million, cached_input_per_million (cache read / hit), cache_write_5m_per_million, and cache_write_1h_per_million. Date-suffix model ids such as claude-haiku-4-5-20251001 fall back to the canonical alias automatically.

Manifest-driven reporting

python scripts/token_usage_cost_report.py report `
  --manifest assets/source-manifest.example.json

Normalized usage reporting

python scripts/token_usage_cost_report.py report `
  --source assets/normalized-usage.example.json `
  --pricing C:\reports\pricing\official-pricing.json `
  --output-dir C:\reports\mixed-runtime-report

Repository dashboard generation

python scripts/build_repository_dashboard.py `
  --reports-root path\to\repository-reports `
  --output path\to\repository-reports\index.html

7. Output Contract

The main report command should produce:

• report.md
• report.html
• report.data.json
• report.sources.json

The report must preserve:

• exact source paths used
• pricing table path used
• official pricing URLs embedded in the resolved pricing table
• warnings for skipped files, unsupported runtimes, unmatched models, and unresolved billing dimensions

Read report-contract.md only when you need the detailed artifact contract.

8. Cost Confidence Rules

Use these labels exactly:

• exact: all observed token categories are covered by the matched pricing row
• estimated: a missing cost component was estimated from peer pricing in the supplied pricing table
• partial: observed token categories or billing modifiers remain unresolved
• unsupported: no trustworthy pricing row matched

Never collapse these labels into a single ambiguous “cost calculated” claim.

9. Narrative Requirements

Every final report should include a concise, non-technical overview that explains:

• what the user asked for
• what work or sessions were analyzed
• why tokens were consumed
• how many user prompts and completed task cycles were observed

Keep the narrative grounded in explicit evidence such as task labels, prompts, outcomes, runtime metadata, and source paths.

10. Review Before Responding

Before replying to the user:

1. Open report.md for a human-readable summary.
2. Open report.sources.json to confirm provenance.
3. Open index.html when you generated a repository dashboard.
4. Read troubleshooting.md only when warnings or partial support need interpretation.

Gotchas

Watch for these common mistakes:

• transcript text, screenshots, and chat summaries are not valid token or cost evidence
• host tooling metadata may describe where work happened, but it does not prove who billed the tokens
• an approximate model name is not enough for exact pricing unless the pricing row clearly matches
• partial and unsupported are correct outcomes when pricing coverage is incomplete or untrustworthy
• Antigravity imports should stay heuristic unless exact token fields are present in the evidence
• a local pricing table is only trustworthy when it was copied from official provider sources and validated before use

Memory Model

Use memory deliberately:

• Runtime memory: evidence paths, extracted tasks, pricing resolution, warnings, and the active reporting state for the current run only.
• Project-local persistent memory: generated reports written to the chosen output directory.
• Shared memory: out of scope. If cross-agent reuse is required, use the agent's own memory (for example CLAUDE.md or AGENTS.md) rather than embedding that concern here.

Do not automatically promote runtime observations into shared or persistent memory.

Failure Handling

If the workflow becomes unreliable:

• missing structured usage evidence: stop and explain why transcript-only costing is refused
• invalid pricing table: validate and repair it before continuing
• invalid normalized usage bundle: validate and repair it before continuing
• missing pricing coverage: fetch official pricing or keep cost labeled partial or unsupported
• heuristic-only evidence: continue only with explicit warnings and clear non-exact labels

Example Request Mapping

Input: Create a cost report for this Codex session.

Result: Generate report artifacts from structured Codex evidence with matched pricing rows and provenance.

Input: Combine these Gemini and Codex sessions into one report.

Result: Use direct Codex parsing plus a normalized Gemini bundle, then emit one combined report with runtime-specific warnings if needed.

Input: Build a TV-friendly dashboard for all repository reports.

Result: Generate the repository dashboard and wallboard entry point from existing per-repository reports.

Resource Map

• README: README.md
• Report contract: references/report-contract.md
• Runtime support: references/runtime-support.md
• Source trust rules: references/source-trust-rules.md
• Pricing rules: references/pricing-sources.md
• Troubleshooting: references/troubleshooting.md