claude-code-usage-monitor
Monitor Claude AI token usage in real-time with ML predictions, cost analytics, and session limit warnings
How do I install this agent skill?
npx skills add https://github.com/reason-machines/claude-code-skills --skill claude-code-usage-monitorIs this agent skill safe to install?
- Gen Agent Trust Hubwarn
The skill provides instructions to install third-party packages from external sources and modify the system shell profile (~/.bashrc) for persistence. It also processes external usage data, which introduces a potential vector for indirect prompt injection.
- Socketpass
No alerts
- Snykwarn
Risk: MEDIUM · 1 issue
What does this agent skill do?
Claude Code Usage Monitor
Skill by ara.so — Claude Code Skills collection.
What It Does
Claude Code Usage Monitor is a real-time terminal monitoring tool that tracks Claude AI token consumption, provides ML-based predictions for session limits, calculates costs, and warns you before hitting usage caps. It supports multiple Claude plans (Pro, Max5, Max20, Custom) with auto-detection, P90 percentile analysis, and intelligent session tracking.
Key capabilities:
- Real-time token/message/cost monitoring with Rich UI
- ML-based P90 predictions for session limits
- Multi-plan support with automatic plan detection
- Cost analytics with model-specific pricing
- Advanced warning system with predictive alerts
- Daily/monthly usage aggregation views
- Auto-detected timezone and time format
Installation
Recommended: Using uv (fastest, isolated)
# Install from PyPI
uv tool install claude-monitor
# Install from source
git clone https://github.com/Maciek-roboblog/Claude-Code-Usage-Monitor.git
cd Claude-Code-Usage-Monitor
uv tool install .
Alternative: Using pip
# Install from PyPI
pip install claude-monitor
# Add to PATH if needed
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
Alternative: Using pipx
pipx install claude-monitor
Basic Usage
Command-Line Interface
The monitor can be invoked with multiple aliases:
# Primary command
claude-monitor
# Alternatives
claude-code-monitor # Full name
cmonitor # Short
ccmonitor # Alternative short
ccm # Shortest
Core Commands
# Default: Custom plan with auto-detection
claude-monitor
# Specify plan type
claude-monitor --plan pro # Pro plan (~44k tokens)
claude-monitor --plan max5 # Max5 plan (~88k tokens)
claude-monitor --plan max20 # Max20 plan (~220k tokens)
claude-monitor --plan custom # Custom with P90 detection
# Custom token limit
claude-monitor --plan custom --custom-limit-tokens 100000
# Change view mode
claude-monitor --view realtime # Live monitoring (default)
claude-monitor --view daily # Daily aggregation
claude-monitor --view monthly # Monthly aggregation
# Configure refresh rates
claude-monitor --refresh-rate 5 # Data refresh (1-60s)
claude-monitor --refresh-per-second 1.0 # Display refresh (0.1-20 Hz)
# Set daily reset time
claude-monitor --reset-hour 3 # Reset at 3 AM
# Theme and display
claude-monitor --theme dark # dark, light, classic, auto
claude-monitor --time-format 24h # 24h or 12h
claude-monitor --timezone "America/New_York"
# Logging
claude-monitor --log-level DEBUG
claude-monitor --log-file ~/claude-monitor.log
claude-monitor --debug
# Utility
claude-monitor --version
claude-monitor --help
claude-monitor --clear # Clear saved config
Configuration
Plan Options
| Plan | Token Limit | Cost Limit | Use Case |
|---|---|---|---|
pro | 44,000 | $18.00 | Claude Pro subscription |
max5 | 88,000 | $35.00 | Claude Max5 subscription |
max20 | 220,000 | $140.00 | Claude Max20 subscription |
custom | P90-based | $50.00 (default) | Auto-detection with ML |
Persistent Configuration
Settings are automatically saved to ~/.claude-monitor/last_used.json:
# First run - save preferences
claude-monitor --plan pro --theme dark --timezone "Europe/London" --refresh-rate 5
# Next run - preferences restored
claude-monitor --plan pro
# Override saved settings
claude-monitor --plan pro --theme light
# Clear all saved preferences
claude-monitor --clear
What gets saved:
- View type (
--view) - Theme (
--theme) - Timezone (
--timezone) - Time format (
--time-format) - Refresh rates (
--refresh-rate,--refresh-per-second) - Reset hour (
--reset-hour) - Custom limits (
--custom-limit-tokens)
Note: Plan selection (--plan) is never saved and must be specified each time.
Python API Usage
While primarily a CLI tool, you can integrate it programmatically:
from claude_monitor.core.config import Config
from claude_monitor.core.data_fetcher import DataFetcher
from claude_monitor.core.analytics import SessionAnalyzer
from claude_monitor.models.plan import Plan
# Create configuration
config = Config(
plan=Plan.PRO,
refresh_rate=10,
theme="dark",
timezone="America/New_York"
)
# Initialize data fetcher
fetcher = DataFetcher(config)
# Fetch current usage
usage_data = fetcher.fetch_usage()
print(f"Tokens used: {usage_data.token_usage}")
print(f"Messages: {usage_data.message_count}")
print(f"Cost: ${usage_data.cost:.2f}")
# Analyze sessions with ML predictions
analyzer = SessionAnalyzer(config)
sessions = fetcher.fetch_sessions()
predictions = analyzer.analyze_sessions(sessions)
print(f"P90 token limit: {predictions.p90_tokens}")
print(f"Predicted session end: {predictions.estimated_end_time}")
Advanced Usage Patterns
Monitoring Long-Running Sessions
# Custom plan optimized for 5-hour sessions
claude-monitor --plan custom --refresh-rate 15
# High-frequency monitoring for critical sessions
claude-monitor --plan max20 --refresh-rate 5 --refresh-per-second 2.0
# Debug mode with file logging
claude-monitor --plan pro --debug --log-file ./monitor.log
Cost Analysis
from claude_monitor.core.data_fetcher import DataFetcher
from claude_monitor.core.config import Config
config = Config()
fetcher = DataFetcher(config)
usage = fetcher.fetch_usage()
# Access cost breakdown
print(f"Total cost: ${usage.cost:.2f}")
print(f"Input tokens: {usage.input_tokens}")
print(f"Output tokens: {usage.output_tokens}")
print(f"Cache tokens: {usage.cache_read_tokens}")
# Model-specific costs
for model, tokens in usage.model_usage.items():
print(f"{model}: {tokens} tokens")
Session Analysis
from claude_monitor.core.analytics import SessionAnalyzer
from claude_monitor.core.data_fetcher import DataFetcher
from claude_monitor.core.config import Config
config = Config(plan=Plan.CUSTOM)
fetcher = DataFetcher(config)
analyzer = SessionAnalyzer(config)
# Fetch last 8 days of sessions
sessions = fetcher.fetch_sessions()
# Analyze with P90 predictions
analysis = analyzer.analyze_sessions(sessions)
print(f"Total sessions: {len(sessions)}")
print(f"P90 tokens: {analysis.p90_tokens}")
print(f"P90 messages: {analysis.p90_messages}")
print(f"P90 cost: ${analysis.p90_cost:.2f}")
print(f"Burndown rate: {analysis.token_burndown_rate:.2f} tokens/min")
Custom Limit Detection
from claude_monitor.core.config import Config
from claude_monitor.models.plan import Plan
# Auto-detect custom limits from usage patterns
config = Config(
plan=Plan.CUSTOM,
# No custom_limit_tokens specified - will use P90 analysis
view="realtime"
)
# Or explicitly set custom limits
config = Config(
plan=Plan.CUSTOM,
custom_limit_tokens=150000, # 150k token limit
view="realtime"
)
Warning System Integration
from claude_monitor.ui.warnings import WarningGenerator
from claude_monitor.core.data_fetcher import DataFetcher
from claude_monitor.core.config import Config
config = Config(plan=Plan.PRO)
fetcher = DataFetcher(config)
warning_gen = WarningGenerator(config)
usage = fetcher.fetch_usage()
warnings = warning_gen.generate_warnings(usage)
for warning in warnings:
print(f"[{warning.level}] {warning.message}")
if warning.suggestion:
print(f" Suggestion: {warning.suggestion}")
Configuration File Format
The monitor stores configuration in ~/.claude-monitor/last_used.json:
{
"view": "realtime",
"theme": "dark",
"timezone": "America/New_York",
"time_format": "24h",
"refresh_rate": 10,
"refresh_per_second": 0.75,
"reset_hour": 0,
"custom_limit_tokens": 100000
}
Environment Variables
# Set timezone
export TZ="America/New_York"
# Configure logging level
export CLAUDE_MONITOR_LOG_LEVEL=DEBUG
# Optional Sentry integration for error reporting
export SENTRY_DSN="your-sentry-dsn"
Common Patterns
Daily Standup Usage Report
# Check yesterday's usage
claude-monitor --view daily --plan pro
# Export to file
claude-monitor --view daily --log-file daily-report.log
Cost Tracking Workflow
# Monitor with cost focus
claude-monitor --plan custom --theme dark --refresh-rate 10
# The custom plan prioritizes cost tracking for long sessions
# Watch the "Cost Usage" bar - most critical metric
Multi-Timezone Team
# Team member in New York
claude-monitor --timezone "America/New_York" --time-format 12h
# Team member in London
claude-monitor --timezone "Europe/London" --time-format 24h
# Team member in Tokyo
claude-monitor --timezone "Asia/Tokyo" --time-format 24h
Performance Optimization
# Low-frequency updates for background monitoring
claude-monitor --refresh-rate 30 --refresh-per-second 0.5
# High-frequency for active development
claude-monitor --refresh-rate 5 --refresh-per-second 2.0
Data Storage
The monitor stores data in ~/.claude-monitor/:
~/.claude-monitor/
├── last_used.json # Saved preferences
├── usage_cache.json # Cached usage data
└── sessions_cache.json # Cached session data
Troubleshooting
Command Not Found
# Check if installed
pip list | grep claude-monitor
# Add to PATH
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
# Or use full path
~/.local/bin/claude-monitor
Externally-Managed-Environment Error
# Solution 1: Use uv (recommended)
uv tool install claude-monitor
# Solution 2: Use pipx
pipx install claude-monitor
# Solution 3: Virtual environment
python3 -m venv ~/claude-monitor-env
source ~/claude-monitor-env/bin/activate
pip install claude-monitor
No Data Showing
# Enable debug logging
claude-monitor --debug --log-file debug.log
# Check API connectivity
cat ~/.claude-monitor/usage_cache.json
# Verify plan limits
claude-monitor --plan custom --custom-limit-tokens 100000
Display Issues
# Force theme
claude-monitor --theme light # or dark, classic
# Reset configuration
claude-monitor --clear
# Check terminal compatibility (requires 24-bit color support)
echo $COLORTERM # Should show "truecolor" or "24bit"
Timezone Problems
# Check system timezone
timedatectl # Linux
date +%Z # macOS
# Force specific timezone
claude-monitor --timezone UTC
# List valid timezones
python3 -c "import zoneinfo; print('\n'.join(sorted(zoneinfo.available_timezones())))"
High CPU Usage
# Reduce refresh rates
claude-monitor --refresh-rate 30 --refresh-per-second 0.5
# Check current settings
cat ~/.claude-monitor/last_used.json
Cache Issues
# Clear all caches
rm -rf ~/.claude-monitor/
# Clear only config
claude-monitor --clear
Integration Examples
Shell Script Integration
#!/bin/bash
# monitor-session.sh
# Start monitoring in background
claude-monitor --plan pro --log-file session.log &
MONITOR_PID=$!
# Your work here
echo "Session started, monitoring in background..."
# Cleanup on exit
trap "kill $MONITOR_PID 2>/dev/null" EXIT
CI/CD Usage Tracking
#!/bin/bash
# Track CI usage
claude-monitor --view daily --plan custom --log-file ci-usage.log
grep "Total Tokens" ci-usage.log | tail -1
Alerting Script
#!/bin/bash
# alert-on-limit.sh
claude-monitor --plan pro --refresh-rate 60 --log-file usage.log &
PID=$!
while true; do
if grep -q "CRITICAL" usage.log; then
echo "Usage limit critical!" | mail -s "Claude Alert" admin@example.com
break
fi
sleep 300
done
kill $PID
API Rate Limits
The monitor respects Claude API rate limits:
- Default refresh: 10 seconds (safe for all plans)
- Minimum recommended: 5 seconds
- Maximum frequency: 1 second (use sparingly)
Performance Tips
-
Optimal refresh rates:
- Active monitoring:
--refresh-rate 10 --refresh-per-second 1.0 - Background monitoring:
--refresh-rate 30 --refresh-per-second 0.5 - Intensive development:
--refresh-rate 5 --refresh-per-second 2.0
- Active monitoring:
-
Resource usage:
- Memory: ~50-100 MB
- CPU: <5% with default settings
- Network: ~1 KB per refresh
-
Cache optimization:
- Session cache: 8 days (192 hours)
- Usage cache: Updated per refresh rate
- Auto-cleanup of old data
Related Tools
- Claude Desktop App (official client)
- Claude API (direct API access)
- Claude Code (IDE integration)
License
MIT License - see project repository for details.
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/reason-machines/claude-code-skills/claude-code-usage-monitor">View claude-code-usage-monitor on skillZs</a>