Claudetop: Real-Time Cost Monitoring for Claude Code Sessions

Claudetop: Real-Time Cost Monitoring for Claude Code Sessions

Claudetop is a monitoring tool for Claude Code that displays real-time cost tracking, cache efficiency metrics, and model comparisons during coding sessions. The tool was created after the developer noticed a discrepancy where model estimates showed $10 but actual billing was $65, with compaction hiding 80% of token usage.

Installation Options

Three installation methods are available:

• Clone and install: git clone https://github.com/liorwn/claudetop.git then cd claudetop && ./install.sh
• One-liner: curl -fsSL https://raw.githubusercontent.com/liorwn/claudetop/main/install.sh | bash
• As a Claude Code plugin: claude plugin marketplace add liorwn/claudetop then claude plugin install claudetop

The plugin installation provides SessionEnd hook plus slash commands automatically: /claudetop:stats, /claudetop:dashboard, /claudetop:branch, /claudetop:export, and /claudetop:pricing.

Display Information

During sessions, Claudetop shows:

• Current project location and depth
• Active model and session duration
• Current cost, hourly burn rate, and projected monthly cost
• Cache efficiency percentage and cost per line
• Comparative costs for other models (Opus, Sonnet, Haiku)
• Token breakdown: input/output percentages with fresh, cwrite, and cread categories

Key Features

Real-time cost tracking: Shows actual session cost (green), burn rate per hour, and monthly forecast extrapolated from history. Pricing updates automatically from pricing.json when Anthropic changes prices.

Model cost comparison: Displays what the session would cost on Opus, Sonnet, or Haiku with cache-aware pricing that accounts for actual cache hit ratio. The current model is bolded for instant comparison.

Cache efficiency monitoring: Cache hit ratio indicates efficiency: green (≥60%) means most input tokens are being reused, red (<30%) indicates something is forcing full re-reads.

Smart Alerts

Alerts appear only when attention is needed:

• $5 MARK / $10 / $25: Cost milestone crossed - gut-check value
• OVER BUDGET: Daily budget exceeded - wrap up or switch models
• CONSIDER FRESH SESSION: >2hrs + >60% context - diminishing returns
• LOW CACHE: <20% cache after 5min - context was reset, tokens being re-read
• BURN RATE: >$15/hr velocity - runaway subagents or tight loops
• SPINNING?: >$1 spent, zero code output - stuck in research loop
• TRY /fast: >$0.05/line on Opus - task doesn't need biggest model
• COMPACT SOON: Context window >80% full - auto-compaction imminent

Session History & Analytics

Every session is automatically logged. Use claudetop-stats with various arguments:

• claudetop-stats - Today's summary
• claudetop-stats week - This week
• claudetop-stats month - This month
• claudetop-stats all - All time
• claudetop-stats tag auth - Filter by tag

This tool is for developers using Claude Code who want visibility into their AI spending patterns and want to optimize model usage and cache efficiency.