usage-report

Track Claude Code token usage across local JSONL transcripts.

Updated Nov 24, 2025
One-click install
npx skills add https://github.com/ByronWilliamsCPA/.claude --skill usage-report
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: usage-report
Source: https://github.com/ByronWilliamsCPA/.claude/tree/main/.claude/skills/usage-report
Command: npx skills add https://github.com/ByronWilliamsCPA/.claude --skill usage-report

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Claude Code users lack built-in visibility into their token consumption, model-specific spend, and five-hour billing block usage across projects and sessions, making it difficult to control costs, enforce model selection policies, and avoid unexpected usage overruns.

Core Features & Use Cases

  • Multi-Mode Usage Reporting: Generate daily, weekly, monthly, session, or billing block summaries of token spend and estimated costs, grouped by project or model.
  • Per-Agent Attribution: For teams using the agents-observe plugin, break down token usage by individual subagents, including delegation chains and model compliance checks.
  • Billing Block Safeguards: Monitor active five-hour billing block consumption and burn rate to prevent overages, with integration for loop circuit breaker checks. Use case: A development team lead can use this skill to pull a weekly spend report to identify if expensive Opus models are being used for low-complexity read-only tasks, violating internal model selection policies.

Quick Start

Use the usage-report skill to generate a weekly summary of your Claude Code token spend and top projects by usage volume.

Frequently Asked Questions about usage-report

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I track Claude Code token usage and costs across projects?

Track Claude Code token usage by parsing local JSONL transcripts to generate per-project and per-session spend summaries without relying on external telemetry backends. Reports group token consumption and estimated costs by project, model, or session.

How does five-hour billing block monitoring work for Claude Code?

Five-hour billing block monitoring tracks active block consumption and burn rate from local usage data to prevent overages. It integrates with loop circuit breaker checks to safeguard against unexpected usage overruns within each billing window.

Can I break down token usage by individual subagents in Claude Code?

Break down token usage by individual subagents using the agents-observe plugin v0.9.11 for subagent-level attribution. This tracks delegation chains and verifies model compliance for cost control and policy enforcement.

Do I need the ccusage CLI tool to generate Claude Code cost reports?

Yes, the ccusage CLI tool is required for standard usage reporting and generating daily, weekly, or monthly cost summaries. The skill applies built-in input validation and safety guardrails for command execution.

What's the best way to enforce model selection policies using Claude Code usage data?

Enforce model selection policies by generating weekly spend reports grouped by model from local JSONL transcripts. Team leads can identify if expensive Opus models are used for low-complexity read-only tasks, violating internal cost controls.

Does Claude Code usage reporting work without external telemetry backends?

Claude Code usage reporting works entirely offline by parsing local JSONL transcripts without external telemetry backends. It calculates token spend, billing block consumption, and per-agent attribution locally with built-in safety guardrails.