摘要
1) 一句话总结
Claude Code Usage Monitor 是一款专为 Claude AI 设计的终端实时监控工具，提供 Token 消耗追踪、成本分析以及基于机器学习的会话限制预测功能。
2) 核心要点
- 基础信息：基于 Python 3.9+ 开发，采用 MIT 开源协议，在 GitHub 上拥有 6640 Stars。
- 多视图监控：提供丰富的终端 UI，支持实时（可配置 0.1-20 Hz 刷新率）、按日和按月三种视图，追踪 Token 消耗、燃烧率及成本（包含缓存 Token）。
- 机器学习预测：内置 P90 分位数计算器，通过分析过去 192 小时（8天）的历史数据，智能检测并预测个性化的会话限制。
- 滚动窗口适配：深度适配 Claude Code 的 5 小时滚动会话机制，精确追踪时间窗口内的 Token 限制。
- 多计划与预警：默认采用动态适应的 Custom 计划，原生支持 Pro、Max5 和 Max20 订阅预设，并提供基于成本和时间的多层级超额警告。
- 智能检测与持久化：自动识别终端背景色和系统时区，并自动保存用户的视图、主题等偏好设置至
~/.claude-monitor/last_used.json。 - 现代化架构：v3.0.0 版本采用模块化设计，使用 Pydantic 进行类型安全配置，并支持可选的 Sentry 错误报告集成。
- 便捷使用：推荐使用
uv或pipx隔离安装，支持claude-monitor、cmonitor、ccm等多种简写命令别名。
3) 风险与限制
- Linux 安装限制：在现代 Linux 发行版（如 Ubuntu 23.04+, Debian 12+）上直接使用 pip 易触发“外部管理环境”错误，官方强烈建议使用
uv或pipx，避免使用--break-system-packages参数。 - 计划参数不保存：工具不会自动保存“计划类型（Plan）”参数，若需使用非默认计划，每次运行均需通过命令行显式指定。
- 环境依赖：严格依赖 Python 3.9 及以上版本环境。
功能与定位
Claude Code Usage Monitor 是一款专为 Claude AI 设计的终端实时 Token 使用量监控工具。它通过丰富的终端 UI（Rich UI）提供高级数据分析、基于机器学习的预测功能，帮助用户追踪 Token 消耗、燃烧率（Burn Rate）及成本，并智能预测会话限制。
典型使用场景
- 长会话监控：在长时间使用 Claude Code 时，实时追踪 Token、消息数量和成本，防止意外超出额度。
- 成本与预算管理：通过按日或按月的数据聚合视图，分析长期使用趋势并进行预算规划。
- 多计划额度管理：针对 Claude Pro、Max5 或 Max20 等不同订阅计划，提供精准的额度预警和消耗分析。
核心功能
- 实时监控与多视图：支持实时（Realtime）、按日（Daily）和按月（Monthly）三种视图。实时视图提供可配置的刷新率（0.1-20 Hz）和智能显示更新。
- 机器学习预测：内置 P90 分位数计算器，通过分析过去 192 小时（8天）的历史会话数据，智能检测并预测个性化的会话限制。
- 成本与消耗分析：提供特定模型的定价计算，包含缓存 Token（Cache token）的成本统计，并分析多会话的消耗模式。
- 智能自动检测：自动识别终端背景色（深/浅色）以优化对比度，并自动检测系统时区和 12h/24h 时间格式。
- 多级预警系统：基于成本和时间预测，提供多层级的超额警告。
- 丰富的终端 UI：提供符合 WCAG 标准的科学配色进度条、可排序的数据表格及自适应终端大小的布局。
特色与差异点
- 专为 5 小时滚动窗口设计：深度适配 Claude Code 的 5 小时滚动会话机制，精确追踪每个时间窗口内的 Token 限制。
- 默认 Custom 计划：默认采用基于 P90 自动检测的 Custom 计划，动态适应用户的实际工作流，而非死板的固定额度。
- 内置多种订阅预设：除 Custom 外，原生支持 Pro（约 1.9万-4.4万 Token）、Max5（约 8.8万 Token）和 Max20（约 22万 Token）计划。
- 配置自动持久化：自动保存用户的视图、主题、时区等偏好设置（存储于
~/.claude-monitor/last_used.json），下次运行无需重复输入参数。 - 现代化架构（v3.0.0）：采用符合单一职责原则（SRP）的模块化设计，使用 Pydantic 进行类型安全配置，并支持可选的 Sentry 错误报告集成。
- 便捷的命令别名：支持
claude-monitor、cmonitor、ccmonitor、ccm等多种简写命令调用。
使用方式概览
- 安装：推荐使用
uv工具进行隔离安装（uv tool install claude-monitor），也可通过pip或pipx安装。 - 基础运行：在终端输入
claude-monitor即可启动默认的智能监控。 - 参数配置：可通过命令行参数覆盖默认设置，例如指定计划（
--plan pro）、切换视图（--view daily）、强制指定主题（--theme dark）或设置自定义重置时间（--reset-hour）。 - 日志与调试：支持输出日志到文件（
--log-file）及调整日志级别（--log-level）。
限制与注意事项
- 环境要求：需要 Python 3.9 及以上版本。
- Linux 安装限制：在现代 Linux 发行版（如 Ubuntu 23.04+, Debian 12+ 等）上使用 pip 可能会遇到“外部管理环境”错误，官方强烈建议使用
uv、pipx或虚拟环境来替代--break-system-packages参数。 - 计划参数不保存：虽然工具会自动保存大部分显示和偏好设置，但“计划类型（Plan）”参数不会被保存，如果需要使用非默认计划，每次运行均需显式指定。