claudetop plugin
claudetop shows session cost, cache hit rate, plan limit windows and overspend alerts in the Claude Code status line
- 212 ★ on the repository
- Last commit
- MIT
Extended access
Why this level
- Reads every Claude Code session JSONL file and keeps spend, projects and tags in a local SQLite database and a log
- For limit windows it uses the stored Claude Code credentials and calls Anthropic servers, but does not refresh or change them
- Registers a SessionEnd hook and replaces the status line
Install
- Works in
In your terminal, with SkillFoxx CLI
npx skillfoxx add plugins/claudetopDetects the agents on your machine, shows the access level and pins the version.
Other ways to install
Access and checks
How we reviewExtended accessThe tool runs code or makes network calls and only reads external data.
- Reads every Claude Code session JSONL file and keeps spend, projects and tags in a local SQLite database and a log
- For limit windows it uses the stored Claude Code credentials and calls Anthropic servers, but does not refresh or change them
- Registers a SessionEnd hook and replaces the status line
This is third-party code. Review the repository files before installing.
What it does
claudetop is a plugin and a set of scripts that turn the Claude Code status line into a spending panel. After every response you see the project, model, session duration, lines added and removed, cost, hourly burn rate and a monthly forecast. A separate line shows plan limit windows: five hours, a week and weekly per-model caps with a countdown to reset. The plugin compares what the same session would cost on Opus, Sonnet or Haiku, using the real cache hit ratio. Prices come from `pricing.json` in the repository and update with it. Alerts fire when cost crosses 5, 10 and 25 dollars, the daily budget is exceeded, the cache drops below 20 percent, spending runs above 15 dollars an hour, or a session spends money without producing code. Sessions are logged, and `claudetop-stats` builds summaries for a day, week and month, including by tag. The `claudetop-engine` scans all Claude Code JSONL files into SQLite and serves a dashboard on `localhost:8080`. A SessionEnd hook and the slash commands `/claudetop:stats`, `/claudetop:dashboard`, `/claudetop:branch`, `/claudetop:export`, `/claudetop:pricing` and `/claudetop:usage` install with the plugin.
Who it is for. Claude Code subscribers and API users who want session cost in front of them instead of a bill at the end of the month.
Good fit when
- The API bill is higher than expected and you need to find which session and model ate the budget
- The plan is close to its weekly cap and switching models in time matters
- The cache works poorly after compaction or a model switch and you want to see it in numbers
- You need a spending summary per task: sessions get a tag through `CLAUDETOP_TAG`
- A team wants a dashboard with an activity heatmap and spend by project, model and tool
Not a fit when
- You use another agent: the plugin reads files and status-line fields that belong to Claude Code
- You need per-employee accounting with a shared database: all data stays local to one user
- Sessions run through Bedrock or Vertex: the plan-window line does not appear in those modes
- You need exact bookkeeping: cost, forecast and model comparison are approximate
Example request
Show this week's spend with claudetop-stats week and tell me which model and project took the mostLimitations
- The plugin works in Claude Code only, and the status line refreshes after every response.
- Plan windows for Pro, Max and Team come from the status-line JSON, while weekly per-model caps and credits are requested from the `/usage` endpoint and cached for a minute in `~/.claude/claudetop-usage.json`. API-key, Bedrock and Vertex sessions do not show this line.
- Forecasts and cross-model comparison are approximate. The author notes that context compaction once hid up to 80 percent of the tokens used.
- The iTerm2 integration needs the terminal itself.
How to disable. Remove the plugin with `claude plugin uninstall claudetop`. A copy installed by `install.sh` is removed by deleting the files and the `statusLine` entry from `~/.claude/settings.json`. The `CLAUDETOP_USAGE=off` variable hides the limits line. The session log stays on disk and must be deleted by hand.
FAQ
How do I install claudetop in Claude Code?
Run `claude plugin marketplace add liorwn/claudetop` and `claude plugin install claudetop`, then restart Claude Code. The alternative is to clone the repository and run `./install.sh`.
How does claudetop differ from ccusage?
ccusage totals spend from session logs in the terminal. claudetop adds a status line inside Claude Code, plan limit windows, cache-aware model comparison and overspend alerts.
Where does the plan limit data come from?
Five-hour and seven-day windows arrive in the Claude Code status line. Per-model limits and credits are fetched by the background `claudetop-usage` command at most once a minute, using credentials Claude Code has already stored.
How do I set a daily budget?
Set the `CLAUDETOP_DAILY_BUDGET` variable, for example `export CLAUDETOP_DAILY_BUDGET=50`. At 80 percent the line shows what is left, and an OVER BUDGET alert appears when it is exceeded.
Does it need external dependencies?
No, the analytics engine uses only the Python 3 standard library: `sqlite3`, `http.server` and `json`.
Discussion
No questions or reviews yet.
Related
PluginsA Claude Code plugin: a status line with context, 5-hour and 7-day limits, cost and usage of Codex, Gemini and z.ai
Terminal manager for Claude Code sessions: live status per session, token cost by model and project, and summaries saved on exit.
A Claude Code status line showing 5-hour and 7-day quota use plus the pace: whether what is left lasts until the window resets
A real-time terminal monitor for Claude Code usage: tokens, messages and cost in the five-hour window, with forecasts and export
A Claude Code plugin that shows a session's CO2 estimate in the status line next to its cost
cc-lens
Claude Code Lens (cc-lens)
Local Claude Code analytics: a dashboard of sessions, tokens, cost and projects from your ~/.claude data, no cloud
Comparison with similar tools
Cards that share the main search query, and how they differ.
| Tool | Official | Repository stars | Main difference |
|---|---|---|---|
| claudetop (this card) | no | 212 | |
| ccusage | no | 19,337 | totals spend from logs in a terminal, without a status line inside Claude Code |
| ccstatusline | no | 13,533 | a configurable status line without spend forecasts or plan limit windows |
README in short
The README starts with the author's story: the model estimate showed 10 dollars while the actual bill was 65, because compaction hid the usage. It then shows the status line, three install options, limit windows, alerts, statistics, the analytics engine, tags, budget, themes and the iTerm2 integration.