# Token Usage

> Analyze Claude Code token consumption and estimated costs across projects and sessions. Use when user asks about token usage, costs, spending, billing, how much they've used, or wants to optimize their Claude Code usage patterns.

- **Type:** Skill
- **Install:** `agentstack add skill-citedy-skills-token-usage`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [citedy](https://agentstack.voostack.com/s/citedy)
- **Installs:** 0
- **Category:** [Web & Browser](https://agentstack.voostack.com/c/web-and-browser)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [citedy](https://github.com/citedy)
- **Source:** https://github.com/citedy/skills/tree/main/skills/token-usage

## Install

```sh
agentstack add skill-citedy-skills-token-usage
```

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

## About

# Token Usage Analyzer

Analyze token consumption patterns and estimate costs from Claude Code session files (`~/.claude/projects/`).

## What It Does

- Parses all JSONL session files to extract token metrics (input, cache creation, cache read, output)
- Groups usage by project and session
- Estimates costs based on Claude model pricing
- Identifies most expensive sessions and subagent usage
- Supports time range filtering (today, week, month, N days, specific date)
- Generates a detailed markdown report

## Usage

Run the analyzer with a time range argument:

```bash
python3 .claude/skills/token-usage/scripts/analyze.py $ARGUMENTS
```

### Arguments

| Argument | Example | Description |
|----------|---------|-------------|
| *(empty)* | | All time |
| `today` | `today` | Since midnight UTC |
| `week` | `week` | Last 7 days |
| `month` | `month` | Last 30 days |
| N (number) | `3` | Last N days |
| Date | `2026-04-01` | Since that date |
| Datetime | `2026-04-01 11:00` | Since that datetime |

### Additional flags

- `--compare` — show current period vs previous period of same length

Example: `--compare week` shows this week vs last week.

### Output

The script prints a summary to stdout and saves a detailed report to:
```
~/.claude/token-usage-reports/token_report.md
```

## Cost Estimation

Prices are per million tokens, detected automatically per model:

| Model | Input | Cache Create | Cache Read | Output |
|-------|-------|-------------|------------|--------|
| Opus | $15.00 | $18.75 | $1.50 | $75.00 |
| Sonnet | $3.00 | $3.75 | $0.30 | $15.00 |
| Haiku | $0.80 | $1.00 | $0.08 | $4.00 |

The analyzer reads the `model` field from each assistant message and applies correct pricing automatically.

## What the Report Includes

1. **Grand totals** — tokens, estimated cost, session count
2. **Model breakdown** — cost split by opus/sonnet/haiku with percentages
3. **Per-project breakdown** — tokens, cost, subagent count per project
4. **Period comparison** — current vs previous period (with `--compare`)
5. **Most costly sessions** — ranked by estimated cost with first prompt preview

## Tips for Reducing Usage

- **Cache read is cheap** ($1.50/M vs $15/M for input) — long conversations benefit from cache
- **Subagents are expensive** — each spawns a fresh context. Use sparingly.
- **Review your costliest sessions** — often one runaway session costs more than a week of normal work
- **Use specific time ranges** to track daily/weekly spending patterns

## Requirements

- Python 3.8+
- Claude Code (session files in `~/.claude/projects/`)
- No external dependencies (stdlib only)

## Source & license

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

- **Author:** [citedy](https://github.com/citedy)
- **Source:** [citedy/skills](https://github.com/citedy/skills)
- **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-citedy-skills-token-usage
- Seller: https://agentstack.voostack.com/s/citedy
- 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%.