# Cc Usage

> Analyze your Claude Code token usage and equivalent pay-as-you-go (API dollar) cost across ALL local projects. Reads the JSONL transcripts under ~/.claude/projects/, dedupes by record uuid, and reports totals, daily/weekly aggregates, per-model or single-model (repriced) cost, top days/weeks, and min/max/median/mean statistics. Trigger when the user asks about "my token usage", "how much would I…

- **Type:** Skill
- **Install:** `agentstack add skill-liberzon-cc-usage-cc-usage`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [liberzon](https://agentstack.voostack.com/s/liberzon)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [liberzon](https://github.com/liberzon)
- **Source:** https://github.com/liberzon/cc-usage

## Install

```sh
agentstack add skill-liberzon-cc-usage-cc-usage
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Claude Code Usage & Cost Analysis

Analyzes the current machine's Claude Code usage from the local transcript store
at `~/.claude/projects//.jsonl`. Each assistant
message carries a `usage` block; this skill sums it across every project and
prices it as if run on the pay-as-you-go API. It reports on whoever is running
it — there is no per-user attribution beyond the local transcripts.

## When to use
- "compute my token usage", "how long is my history", "total input/output tokens"
- "how much would I have paid without a subscription", "what's my API-equivalent cost"
- "max daily / weekly consumption", "top days", "weekly spend min/max/median/mean"
- "what if I ran everything on Fable / Opus / Sonnet / Haiku"

## How to run

Everything is in `scripts/usage.py` (Python 3 stdlib only, no dependencies):

```bash
python3 "$CLAUDE_SKILL_DIR/scripts/usage.py" [flags]
```

If `$CLAUDE_SKILL_DIR` is unset, use the skill's own directory (e.g.
`~/.claude/skills/cc-usage/scripts/usage.py`).

Common invocations:
- Totals + all-time summary (span, input/output/cache tokens, $): no flags
- Max daily consumption: `--by day --top 10` (add `--rank cost` to rank by $)
- Per-week tokens + $: `--by week`
- Clean weekly stats: `--by week --full-weeks-only --stats`
- Reprice everything at one model: add `--model fable` (or opus/sonnet/haiku)

## Accounting rules (already encoded in the script — do not re-derive)
- **Dedup by the record `uuid`** (the canonical per-record key). Consider every
  record that carries a `usage` dict; skip anything else. Subagent/sidechain
  sessions live in separate files but each message has its own uuid, so they are
  additive and counted once. Do NOT dedupe by `(message.id, requestId)` — that
  collapses genuinely-distinct messages (null/repeated message ids) and undercounts
  by ~2×.
- **"Total tokens"** = `input + output + cache_read + cache_creation`. This is
  dominated by cache traffic; the raw input+output is far smaller (Claude Code
  re-reads the cached context every turn). Always say so when reporting totals.
- **Cost** uses the actual per-message `message.model` mix by default. Rates per
  1M tokens: Opus $5/$25, Sonnet $3/$15, Haiku $1/$5, Fable $10/$50. Unknown models
  fall back to the Opus tier. Update `RATES` in the script if list prices change.
- **Cache pricing** off the base input rate: read ×0.1, 5-min write ×1.25,
  1-hour write ×2.0. Writes are split via `usage.cache_creation.ephemeral_{1h,5m}_input_tokens`;
  if unsplit, `cache_creation_input_tokens` is treated as 5-min.
- **Weeks** are ISO weeks (`date.isocalendar()`). `--full-weeks-only` drops the
  first and last ISO week of the covered span (their coverage is clipped by the
  data boundaries) — a low-usage *middle* week is NOT partial and is kept. Use
  this before quoting weekly statistics, since the boundary weeks skew the
  distribution.

## Reporting guidance
- `--model` gives a strict **upper bound** — you would never realistically run
  bulk Haiku-tier work on the top model. Say so when repricing at Fable.
- The distribution is **right-skewed** (ramp-up weeks vs steady-state): median ≪ mean.
  Call that out rather than reporting mean alone.

## Files
- `scripts/usage.py` — the whole analysis; stdlib-only, safe to run read-only.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [liberzon](https://github.com/liberzon)
- **Source:** [liberzon/cc-usage](https://github.com/liberzon/cc-usage)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-liberzon-cc-usage-cc-usage
- Seller: https://agentstack.voostack.com/s/liberzon
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.