usage-meter
Where every token goes: limit %, tokens and API $, plus a cache-expiry countdown.
Illustration. Actual results depend on the mod, terminal and environment.
Install
Installation is unusual; follow the original author’s instructions
Read the author’s instructions ↗What it accesses
Based on the author’s documentation, checked when listed; use claude plugin validate to check for yourself.
Reads
YesThe collector reads ~/.claude/projects transcripts, Codex logs and configured stream-json logs; the mod reads summaries.
Writes files
YesWrites the ledger, limit readings and stop requests under ~/.claude/usage-meter; install links and adds a service.
Runs commands
YesResident Python collector; runs ssh for sync and claude auth status; stopping Codex sends SIGINT/SIGTERM.
Network
YesWith peers set, the collector syncs over SSH every 20 s; with idle compaction on, compacting makes a model request.
Introduction
usage-meter is a Claude Code mod with a background Python collector that shows your plan-limit %, tokens and API-equivalent dollars live, split by machine, session, subagent, prompt and model.
- Where: the status line, a live band above the prompt, and a
/burnpane. - Limit % learned from your data: it fits how fast each model burns your 5-hour and weekly limits, so budget left is in real terms.
- API-equivalent $: every request at list prices, cache writes by TTL.
- Every machine in one view: a collector on each box, synced over SSH; also follows Codex runs and can stop them.
- v0.3.0 cache countdown: after 10 minutes idle, the band shows when the session's prompt cache expires (on by default).
- v0.3.0 idle auto-compact (off by default): sessions with 150k+ tokens of context are compacted once, 5 minutes before the cache expires.
- v0.3.0 headless runs: with
streamLogsset, it countsclaude -pstream-json logs.
Needs Python 3.9+ on Linux or macOS: clone, then run deploy/install.sh; settings live in /plugin configure usage-meter. No Claude Code version stated.
Who it is for
- Heavy users across machines, with Claude Code and Codex, who want exact limit burn
Requirements
- Needs Python 3.9+ on Linux or macOS; installed with deploy/install.sh, not a marketplace.
- No Claude Code version stated; multi-machine sync needs key-based SSH.
- Idle compaction is off by default; enable it via /plugin configure usage-meter.