SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场claude-code-usage-monitor

claude-code-usage-monitor

部署与运维

查看项目

更新于 10-16 11:36

技能介绍

用途

Claude Code Usage Monitor 是一个实时终端监控工具，用于跟踪 Claude AI 的 token 消耗量。它能够基于机器学习预测会话限制，计算成本，并在触及用量上限之前向你发出警告。

主要能力

  • 带 Rich UI 的实时 token／消息／成本监控
  • 基于 ML 的 P90 会话限制预测
  • 多套餐支持，并带自动套餐检测
  • 带按模型定价的成本分析
  • 带预测性告警的高级警告系统
  • 每日／每月用量聚合视图
  • 自动检测时区与时间格式

安装

推荐方式：使用 uv（最快，隔离环境）

# 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 .

备选方式：使用 pip

# Install from PyPI
pip install claude-monitor

# Add to PATH if needed
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

备选方式：使用 pipx

pipx install claude-monitor

使用方式

命令行界面

该监控工具可通过多个别名调用：

# Primary command
claude-monitor

# Alternatives
claude-code-monitor  # Full name
cmonitor            # Short
ccmonitor           # Alternative short
ccm                 # Shortest

核心命令示例：

# 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

套餐选项

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

持久化配置

设置会自动保存到 ~/.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

会保存的内容：视图类型（--view）、主题（--theme）、时区（--timezone）、时间格式（--time-format）、刷新率（--refresh-rate、--refresh-per-second）、重置小时（--reset-hour）、自定义限制（--custom-limit-tokens）。

注意：套餐选择（--plan）永远不会被保存，每次必须指定。

配置文件格式示例：

{
  "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
}

Python API 用法

虽然它主要是 CLI 工具，但也可以编程集成：

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}")

环境变量

# 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"

适用场景

  • 每日站会用量报告：claude-monitor --view daily --plan pro
  • 成本跟踪工作流：claude-monitor --plan custom --theme dark --refresh-rate 10
  • 多时区团队：通过 --timezone 与 --time-format 为不同地区成员配置
  • 性能优化：后台监控使用低频刷新（--refresh-rate 30 --refresh-per-second 0.5），活跃开发使用高频刷新（--refresh-rate 5 --refresh-per-second 2.0）
  • 长时间运行会话监控、CI/CD 用量跟踪、告警脚本集成（Shell 脚本示例见资料）

数据存储

监控工具将数据存储在 ~/.claude-monitor/：

~/.claude-monitor/
├── last_used.json          # Saved preferences
├── usage_cache.json        # Cached usage data
└── sessions_cache.json     # Cached session data

限制与注意事项

  • 尊重 Claude API 速率限制：默认刷新 10 秒，最低建议 5 秒，最高频率 1 秒（谨慎使用）。
  • 资源占用：内存约 50-100 MB，默认设置下 CPU <5%，每次刷新网络约 1 KB。
  • 缓存：会话缓存 8 天（192 小时），用量缓存按刷新率更新，旧数据自动清理。
  • 显示需要终端支持 24 位色（echo $COLORTERM 应显示 "truecolor" 或 "24bit"）。
  • 常见故障排查：命令未找到（加入 PATH 或使用完整路径）；Externally-Managed-Environment 错误（改用 uv、pipx 或虚拟环境）；无数据显示（启用 debug 日志、检查 API 连通性、验证套餐限制）；显示问题（强制主题、重置配置）；时区问题（强制指定时区或列出有效时区）；高 CPU 占用（降低刷新率）；缓存问题（删除 ~/.claude-monitor/ 或使用 --clear）。

许可：MIT License。