Claude Code sessions can be deceptively expensive: a terminal window may feel like a quick iteration loop, but the billing dashboard later tells a different story. claudetop is a CLI/status-line tool designed to close that gap by surfacing real-time token and dollar spend directly inside Claude Code—alongside cache behavior, context usage, and quick comparisons across models.
At a glance, claudetop aims to act like an “htop” for prompting: a compact status readout that keeps cost visible while work happens, rather than after the fact.
What claudetop shows during a session
Once installed, claudetop replaces the “blank prompt” vibe with a multi-line status display that includes project context, active model, session duration, tokens in/out, and live cost—including a burn rate per hour and a monthly forecast extrapolated from recent history.
It also surfaces cache efficiency (cache hit ratio) and breaks down inbound context composition, such as how much of the input is fresh versus cache reads/writes. That’s especially relevant for longer sessions where compaction and context churn can make actual token usage diverge from a mental estimate.
Cost comparisons across models (with cache-aware pricing)
A central feature is model cost comparison: claudetop estimates what the current session would cost on Opus, Sonnet, or Haiku, while accounting for cache read/write rates based on the session’s cache hit ratio. Pricing is pulled from the repo’s pricing.json, and the project describes pricing updates as occurring daily.
The README also includes a “Current pricing” table (Claude 4.6, March 2026) and notes that extended thinking tokens are billed at standard output rates.
Smart alerts for runaway spend and context issues
claudetop includes alerts that appear only when something crosses a threshold—covering cost milestones (like $5 MARK), daily budget overruns, “low cache” warnings, high burn rate, and context-window pressure (for example, COMPACT SOON when context usage exceeds 80%). There’s also a “spinning” detector intended to flag money spent without code output.
History, tagging, budgets, and themes
Beyond the live status line, claudetop logs sessions for history and analytics via the included claudetop-stats tool, with time range summaries and breakdowns by model and project. It supports session tagging via CLAUDETOP_TAG, plus a daily budget environment variable (CLAUDETOP_DAILY_BUDGET) that shows remaining budget and triggers an over-budget warning.
Display can be adjusted via themes: full (default, 3–5 lines), minimal (2 lines), and compact (1 line).
iTerm2 integration and extensible status plugins
For iTerm2 users, claudetop can push session data into iTerm2 chrome: tab titles, badges, status bar variables, and even background color tinting based on session state (healthy/caution/alert). On other terminals, iTerm2 escape sequences are treated as a no-op.
The tool is also extensible: dropping an executable into ~/.claude/claudetop.d/ adds it to the status line. The repo includes a default git-branch.sh plugin and example plugins like Spotify “now playing,” GitHub Actions CI status, weather, and a ticket ID derived from the current branch name.
Installation, requirements, and license
claudetop can be installed by cloning the repo and running an install script, by a curl one-liner that pipes install.sh to bash, or as a Claude Code plugin via:
claude plugin marketplace add liorwn/claudetopclaude plugin install claudetop
Requirements listed are Claude Code with status line support, plus jq and bc. The project is MIT licensed and, per the GitHub release listing, has a v1.0.0 release dated Mar 14, 2026.
