# Claude Usage Report

> Aggregate Claude Code usage (tokens, sessions, API-equivalent cost) by day, week, month, model, and project from local JSONL session logs. Use when the user asks about their Claude Code usage, consumption, costs, "cuánto he usado", "uso diario/semanal/mensual", or wants to audit which projects/models are eating the most tokens.

- **Type:** Skill
- **Install:** `agentstack add skill-carloscape-octorato-claude-usage-report`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [CarlosCaPe](https://agentstack.voostack.com/s/carloscape)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [CarlosCaPe](https://github.com/CarlosCaPe)
- **Source:** https://github.com/CarlosCaPe/octorato/tree/master/skills/claude-usage-report
- **Website:** https://www.dataqbs.com/octorato

## Install

```sh
agentstack add skill-carloscape-octorato-claude-usage-report
```

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

## About

# Claude Usage Report

## Purpose

Claude Code stores every assistant message — including token usage and model
identity — in JSONL files under `~/.claude/projects/`. This skill parses those
logs and produces a usage breakdown so the operator can:

- See daily / weekly / monthly activity at a glance.
- Identify which projects and models are driving cost.
- Spot anomalies (sudden spike, idle weeks, model drift).
- Quantify the "value extracted" from a Claude Max/Pro subscription vs paying
  per-token at API list price.

## Triggers

Activate when the user asks any of:

- "¿cómo va mi uso de Claude?" / "how is my Claude usage?"
- "uso semanal" / "uso mensual" / "uso diario"
- "cuánto he gastado en Claude" / "Claude usage stats"
- "qué proyecto consume más tokens"
- "qué modelo uso más"
- Any audit-style question about Claude Code consumption.

## Workflow

### 1. Run the aggregator

```bash
python3 ~/.claude/skills/claude-usage-report/scripts/usage_report.py
```

Optional flags:

- `--days 30` — show last 30 days of detail (default 14)
- `--json` — emit machine-readable output (useful for piping into other tools)
- `--projects-dir PATH` — override the default `~/.claude/projects/` location

### 2. Output sections (in order)

1. **Header** — files scanned, lines, messages with usage data
2. **ÚLTIMOS N DÍAS** — day-by-day breakdown (sessions, msgs, tokens, $)
3. **POR SEMANA** — last 8 ISO weeks
4. **POR MES** — every month with activity
5. **POR MODELO** — sorted by cost, shows which model dominates spend
6. **POR PROYECTO** — top 10 projects by cost (uses cwd-derived names)
7. **TOTAL ACUMULADO** — grand totals + cost note

### 3. Interpret with the user

Use the output to answer their actual question. Common follow-ups worth
volunteering:

- If Opus dominates >80% of cost: "Sonnet handles ~80% of typical work at 1/5
  the price — worth considering for non-critical tasks."
- If cache reads are large vs input tokens: "Prompt caching is saving you ~X.
  Keeping sessions warm matters."
- If a single day is an extreme outlier: name it and check it's expected.
- If sessions count is high but msgs/session low: many short interruptions —
  consolidating may help cache hit rate.

## Pricing source

The script embeds Anthropic public list prices (USD per 1M tokens) for the
Claude 4.x family. Pricing categories: `in`, `out`, `cache_w` (cache write),
`cache_r` (cache read).

When Anthropic updates prices or releases new models, edit the `PRICING` dict
at the top of `scripts/usage_report.py`. Unknown models fall back to family
heuristics (opus / sonnet / haiku) so the report still produces a number.

## Best practices

- **Don't conflate cost with payment.** With a Claude Max/Pro subscription the
  dollar figure is "what this would cost at API list price" — i.e. value
  extracted, not money owed. Always state this when reporting.
- **Cache read is the cheapest token type** (~5% of input price) — high cache
  read volume is good news, not bad.
- **Synthetic messages** (model = ``) are harness-generated, not
  billed. They appear in counts but with $0.
- **Empty sessions** (msgs but no `usage` field) exist because Claude Code
  sometimes writes user-only lines or aborted turns. The aggregator skips
  records without `usage`, which is correct.

## Error handling

- **Empty `~/.claude/projects/`** — script exits with a clear error. Suggest
  running Claude Code at least once first.
- **Malformed JSONL lines** — silently skipped per line (logs sometimes have
  truncated tails after crashes).
- **Unknown model name** — falls back to family heuristic via substring match.
  If neither opus nor haiku is in the name, defaults to Sonnet pricing.

## Lessons Learned

- **Don't trust `npx` for one-off tools in restricted environments.** The
  canonical community tool for this (`ccusage`) is great but is blocked by
  Claude Code's auto-mode classifier (external code execution). Parsing the
  JSONL directly with Python avoids that gate entirely.
- **Project names come from `cwd`-derived directory names**, e.g.
  `-home-user-Documents-github-foo`. The script strips the home prefix
  generically (no hardcoded usernames) so the same code works for any operator.
- **ISO weeks ≠ calendar weeks.** Use `datetime.isocalendar()` to match what
  most billing dashboards report. Don't roll your own week math.
- **`cache_creation_input_tokens` is expensive** (1.25× input price) — a
  session that writes huge cache once then reads it many times is optimal;
  one that re-writes cache every turn burns money.

## Source & license

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

- **Author:** [CarlosCaPe](https://github.com/CarlosCaPe)
- **Source:** [CarlosCaPe/octorato](https://github.com/CarlosCaPe/octorato)
- **License:** MIT
- **Homepage:** https://www.dataqbs.com/octorato

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-carloscape-octorato-claude-usage-report
- Seller: https://agentstack.voostack.com/s/carloscape
- 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%.