agentsclimarketplace
Sign in

Token limit tracker

Skill adamoakleyew/claude-skills/token-limit-tracker

Visualize and optimize Claude Code token usage from local transcripts: hourly/daily/weekly/monthly burn by model, estimated remaining plan headroom (5h session + weekly windows), cache economics, and computed optimization findings. Triggers on: '/token-limit-tracker', 'show my token usage', 'how many tokens have I used', 'am I close to my Claude limit', 'when does my session window reset', 'optimize my token usage', 'token dashboard'. Does NOT fire for API billing questions (this reads Claude Code transcripts, not the API console).From its SKILL.md

Install
npx -y skills add adamoakleyew/claude-skills --skill token-limit-tracker

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

  • 0 stars0 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

SKILL.md

3.7 KB, 766 tokens by cl100k_base, as published. Nobody here has run it

token-limit-tracker: see and optimize your Claude Code tokens

Renders a local dashboard.html from the transcripts Claude Code already keeps on this machine. Everything runs locally; nothing is uploaded.

Run

python3 token_tracker.py            # incremental scan + render + open
python3 token_tracker.py --full     # first run, or full rebuild of last ~30 days
python3 token_tracker.py --no-open  # headless (for scheduled runs)

Run from this skill's directory. First run takes a few seconds; incremental runs parse only transcripts that changed.

What to tell the user after a run

  1. Report the three gauge percentages (session 5h, weekly all models, weekly premium) and when each resets. Always call them estimates.
  2. If any gauge is over 70%, lead with that and what it means for the rest of the window.
  3. Surface the Optimization findings section verbatim if it flagged anything.
  4. If budgets are uncalibrated (gauges read "-" or look wrong), walk the user through calibration (below).

Calibration (the gauges are estimates)

Anthropic does not publish per-plan token limits, and they vary. The gauges compare burn against budgets in config.json (copy config.example.json). To calibrate:

  1. Run /usage inside Claude Code and note its session + weekly percentages.
  2. Compare with the dashboard gauges.
  3. Scale session_5h_units, week_units, week_premium_units proportionally until they match (e.g. dashboard says 40%, /usage says 60%: multiply the budget by 40/60).
  4. Set week_reset_anchor to the reset time /usage shows (ISO format). Until then the weekly gauges use a rolling 7 days.

Burn is measured in "usage units" (list-price USD equivalent), because plan limits meter compute cost, not flat token counts.

Keeping it current (recommended)

Claude Code prunes transcripts after ~30 days; the ledger in data/ledger.json is what preserves history, so collection should run at least daily. On macOS:

./install-launchd.sh     # hourly background collection, logs to ~/Library/Logs/
./install-launchd.sh --uninstall

On Linux, a cron line works: 0 * * * * cd <this dir> && python3 token_tracker.py --no-open.

Never delete data/ledger.json. It holds history the transcripts no longer have. Rebuilding from scratch recovers only the last ~30 days plus whatever daily totals Claude Code's stats cache still has.

Optional burn alert

Set alert_command in config.json to any shell command; {message} is replaced with the alert text. It fires once per weekly window when premium burn crosses alert_pct (default 80). Example (macOS notification):

"alert_command": "osascript -e 'display notification \"{message}\" with title \"Claude tokens\"'"

Troubleshooting

  • Gauges all read 0% with recent usage: the ledger is new; run --full once.
  • Weekly gauge seems wrong: set week_reset_anchor; rolling 7 days over- or under-counts near a reset boundary.
  • A model shows as "Other": its id is new; the family map in token_tracker.py matches on substrings (fable/opus/sonnet/haiku) and is easy to extend.

What ships with it: 5 files

245.6 KB alongside SKILL.md, 2 of them executable

assets/

Keep looking

Skills are one crate of 326,852. Ordering is by how many stacks a row turns up in, so the top of any crate is what has actually been picked rather than what has the most stars.