AI 应用CLI【免费下载链接】Claude-Code-Usage-MonitorReal-time Claude Code usage monitor with predictions and warnings项目地址https://gitcode.com/gh_mirrors/cl/Claude-Code-Usage-Monitor点击查看免费下载claude-monitor 是一款面向 Claude Code 的实时用量监控工具项目全称 Claude-Code-Usage-Monitor包名claude-monitor其 CHANGELOG.md 完整记录了它从 1.0.6 到 4.0.0 的演进主线。本文以这份变更记录为骨架结合 src/claude_monitor 下的源码实现逐条拆解每个版本的关键修复与新增能力帮助读者理解官方限额信任层statusline— 机器可读快照协议 — 持久化仓库这一 4.0.0 时代的三层架构并掌握每个 CLI 参数背后对应的实现位置。读完本文你将能够看懂--statusline/--once/--compact/--write-state/--warehouse等核心开关的作用与原理理解 P90 限额、5 小时滚动窗口、--reset-hour重置语义等关键算法并知道每个修复点在源码中的位置便于后续排查与二次开发。一、版本地图一条从ccusage 包装器到Usage-Ops Companion的演进主线CHANGELOG 按倒序排列了从 4.0.0 到 1.0.6 的全部变更。将其按主题归类可以得到清晰的演进脉络版本变更记录中的日期核心主题4.0.0Unreleased未标注官方限额信任层、快照协议、持久化仓库、多源输入、定价与时间语义全面修正3.1.02025-07-23--view realtime/daily/monthly三种时间聚合视图3.0.02025-01-13单文件 →src/claude_monitor/模块化架构重写、包更名、Python 3.92.0.02025-06-25智能主题系统亮/暗色自动检测1.0.19 / 1.0.17 / 1.0.162025-06-22 ~ 23时区锁定、加载屏、ccusage 依赖健壮化1.0.11 / 1.0.8 / 1.0.7 / 1.0.62025-06-21 ~ 22现代打包、Node/npx 依赖处理、终端恢复值得注意的一个细节从时间戳看 2.0.02025-06-25晚于 3.0.02025-01-13说明这份 CHANGELOG 是按功能分支合并而非严格时序排布的记录阅读时应以功能主题而非日期顺序为准。早期的 1.x 版本本质上是ccusage一个 npm 工具的 Python 包装器负责调用外部命令解析 Claude Code 的 JSONL 日志从 3.0.0 起它被彻底重写为自包含的模块化 Python 包4.0.0 则把它推向Usage-Ops Companion——不仅能监控还能提供可信的官方限额数据、机器可读协议和持久化历史。当前仓库的 README.md 开篇即将其定位为 A privacy-first Claude Usage-Ops companion for Claude Code。二、4.0.0Unreleased三层能力跃迁4.0.0 是 CHANGELOG 中篇幅最大、信息密度最高的部分包含 20 项 Bug Fixes 与 15 项 Features。按主题可划分为七个板块。2.1 官方限额信任层--statusline与confidence溯源体系4.0.0 最具架构意义的变化是引入了官方数据优先的信任层--statusline作为 Claude Code 的 statusline 钩子运行从 stdin 读取会话 JSON捕获官方rate_limits5 小时与 7 天窗口的used_percentageresets_at适用于 Claude Code 2.1.80 的 Pro/Max 用户输出一行状态栏。在 Claude Code 的 settings.json 中配置statusLine: {type: command, command: claude-monitor --statusline}。捕获结果写入~/.claude-monitor/statusline/latest.json见 src/claude_monitor/output/official.py 的default_statusline_path()快照侧通过read_official_limits()读回。新鲜度窗口 600 秒10 分钟OFFICIAL_TTL_SECONDS 600超过该窗口的捕获被标记stale不再驱动显示的 reset、状态或confidence: official标签而是回退到本地估算并标注stale。健壮性防护_clean_pct()会剔除 JSON 允许的NaN/InfinityPython 的json默认接受它们会撑爆int()转换针对已知泄漏 bugused_percentage偶尔携带resets_at时间戳做了略大于 100 视为舍入、epoch 量级值直接丢弃的守卫capture_statusline()用 pid 唯一临时文件 os.replace原子写入并会在无rate_limits时写入 tombstone 以清除历史官方数据。状态栏格式化为模型名 · 5h xx% · 7d xx%任何异常都回退为claude-monitor绝不空白见 src/claude_monitor/cli/main.py 的_run_statusline()。当存在新鲜官方捕获时快照的limits.five_hour/limits.seven_day会切换为confidence: official且 5 小时值直接驱动--once的退出码没有捕获时所有数字都是明确标注的本地估算local_estimate。这正是信任层的含义来源可见、置信度可查、回退可解释。2.2 机器可读快照协议--once、--compact、--write-state4.0.0 把给脚本/CI/状态栏消费的数据从 Rich TUI 中独立出来统一为一个版本化快照契约src/claude_monitor/output/snapshots.py--once --output {rich,json,text}一次性采集、打印快照后退出避免解析 TUI。快照含schema_version当前1.0、source、confidence、limits、local、local_history、forecast等字段所有数字都带local_estimate标注。自动化退出码0正常、10接近限额、11命中限额、20不确定/无活动会话、30无数据或配置错误。实现位于_status()见 src/claude_monitor/cli/main.py 与 snapshots.py有真实 utilization如官方限额时即使没有本地活动会话也照常驱动退出码只有 utilization 未知且无本地会话时才返回20。--write-state持续把同一份快照写入状态文件默认~/.claude-monitor/state/latest.json可用--state-file覆盖供状态栏、托盘应用、仪表盘轮询。写入是原子的pid 唯一临时文件 os.replace见 src/claude_monitor/output/state.py读者永远不会看到半个文件。--compact单行输出——用量百分比、已用/限额 tokens、燃烧速率、重置时间、会话成本一行搞定live 模式原地更新与--once共用同一快照构建器数字永不分叉。--set-terminal-title与--title-format用快照更新终端标题模板支持pct、plan、used、limit、cost、reset六个键默认{pct}% {plan}。模板在 src/claude_monitor/core/settings.py 的validate_title_format中被严格校验——未知键直接报错而不是发明一套新 DSL。Pace 与预报增强快照新增带来源标注的 pace 指标基于 5 小时 reset 计算used_pct与elapsed_pct的差值10点提示slow down、-10点提示speed up、其余on tracklocal_history明确标注为历史预报用Today/Tomorrow/日期上下文 (estimated)标签命中限额后预报冻结不再预测超出限额的时间点见 snapshots.py 中limit_hit分支。--compact额外输出一个pace...token且仅当官方seven_day状态栏块存在时才渲染7d。2.3 持久化使用仓库与报表--warehouse提供了跨越 Claude 30 天清理周期的本地持久化能力src/claude_monitor/data/warehouse.py默认关闭--warehouse-file控制位置默认~/.claude-monitor/warehouse/usage.json--warehouse-retention-days控制保留天数默认 365最小 1。实现刻意保持零依赖JSON 文件 版本化 schemaWAREHOUSE_SCHEMA_VERSION 1.0 原子替换写入按key去重 upsert按day/project/model/timestamp排序保留策略在_prune_records()中执行。维度覆盖 source / account / project / model / day 五级另有limit_events记录被检测到限额结束的会话。报表导出--view entries|sessions|burn-rate --output json|csv从仓库构建报表src/claude_monitor/data/reports.py输出带 source/provenance 字段的合法 CSV/JSON含会话数、P50/P90/P95 分位、限额结束会话数、燃烧速率行以及明确标注为估算的计划推荐。导出视图在 src/claude_monitor/cli/main.py 的_run_warehouse_report()中实现仅接受json/csv两种输出。2.4 多源数据输入--data-paths、CLAUDE_CONFIG_DIR、WSL数据源发现逻辑在discover_claude_data_paths()见 src/claude_monitor/cli/main.py--data-paths可重复或逗号分隔传入多个 Claude 数据目录不再塌缩到第一个路径。CLAUDE_CONFIG_DIR优先设置时$CLAUDE_CONFIG_DIR/projects支持逗号分隔多目录在标准位置之前被检查路径发现还会去重重复目录。WSL 附加发现在 WSL 环境下附加发现 Claude 数据路径_wsl_claude_paths()通过WSLDetector。标准位置为~/.claude/projects与~/.config/claude/projects。多条数据源被去重、打上source.kind与账户路径标签并按来源拆分为独立的 5 小时窗口避免多个 profile/账户被合并进同一个限额窗口。无数据诊断对应 #110找不到数据目录时_no_data_diagnostic()会列出实际搜索过的全部路径并提示请至少使用过一次 Claude Code 以生成 JSONL 日志替代原来的一行干巴巴报错。2.5 定价与模型归属修正定价逻辑集中在 src/claude_monitor/core/pricing.py 的PricingCalculator新模型价格更新Opus 4.5 按 $5/$25输入/输出缓存创建 $6.25、缓存读取 $0.5计费——此前按旧版 $15/$75 计价相当于 3 倍超收Haiku 4.5 按 $1/$5Fable 5 按 $10/$50。FALLBACK_PRICING同时覆盖 Sonnet$3/$15。旧模型保留原价LEGACY_PRICING中 Opus 3/4.0/4.1 保持 $15/$75Haiku 3/3.5 保持 $0.25/$1.25 与 $0.8/$4。非 Anthropic 模型不再伪装成 Claude 计价经 Claude Code Router 路由进来的 GPT/DeepSeek 等模型此前会被静默按 Sonnet 费率计费导致成本虚高现在无法识别的非 Anthropic 模型按 $0 计价UNKNOWN_PRICING未知但明显是 Claude 的模型仍走家族回退_get_pricing_for_model末尾按 fable/opus/haiku/claude/sonnet 关键词回退。成本公式(input/1M)*in_rate (output/1M)*out_rate (cache_creation/1M)*1.25*in_rate (cache_read/1M)*0.1*in_rate结果保留 6 位小数并按 key 缓存。--filter-models anthropic#113只统计 Claude 模型把非 Anthropic 的 routed 模型从用量、成本与限额计算中剔除对 live 视图、one-shot/state 输出以及日/月表格一致生效默认all不改变行为。2.6 时间语义与重置逻辑修复这批修复#95/#96/#106/#114/#188/#98/#121/#220集中在重置时间的语义一致性上--reset-hour真正生效此前该参数被接受、被持久化却从未参与计算。现在它设定日/月表格视图中的每日滚动边界——一个使用日从reset_hour到reset_hour例如--reset-hour 4时 02:00 计入前一天而不是午夜到午夜。实现位于 src/claude_monitor/data/aggregator.pyshift timedelta(hoursself.reset_hour or 0)按显示时区对本地小时分桶。它刻意不移动滚动 5 小时窗口——后者来自会话/官方数据。重置时间优先采纳 Claude 自己报告的会话块含带 reset 时间的限额消息时显示该时间而非开始时间5 小时估算与 Claude 实际告知的重置一致官方 statusline 限额仍优先。Epoch 重置时间戳按 UTC 解析limit reached|epoch中的数字时间戳此前被当作本地墙钟时间解析并误标为 UTC在非 UTC 机器上如中欧相差两小时导致显示偏移现在 epoch 按其本义——绝对 UTC 时刻——解析。Windows 与本地时区检测改用 IANA 时区Windows 自动检测改用tzlocal拒绝把Eastern Standard Time这类裸tzutil标签当作合法pytz时区--timezone local别名在显示代码运行前即完成解析新增伊斯坦布尔重置显示的回归测试防止 reset 时间漂移一小时。相关时区工具位于 src/claude_monitor/utils/timezone.py 与 src/claude_monitor/utils/time_utils.py。2.7 显示、兼容与参数持久化修复模型分布条展示所有家族#124/#164ModelUsageBar现在渲染 Sonnet、Opus、Haiku 以及一个Other桶不再只显示 Sonnet/Opus——Haiku 与其他模型不再从用量条消失或扭曲百分比。快照侧_family_of()按模型名关键词归类见 src/claude_monitor/output/snapshots.py。Rich TUI 使用官方感知的限额覆盖层live 视图与 Rich--once输出改用与 compact/state/export 相同的快照新鲜 statusline 限额可驱动显示的 5 小时百分比并带official标签不再显示冲突的本地估算条。Time to Reset 对齐与 Windows 字形回退#144/#160进度行按wcwidth的终端显示宽度补齐时钟 emoji 不再推移进度条启动时尽量强制 UTF-8 输出非 UTF-8 Windows 流启用 ASCII 回退。Plan 持久化#162选定的--plan持久化到last_used.json并在下次运行恢复命令行显式--plan优先。见 src/claude_monitor/core/settings.py 的LastUsedParams保存 plan/theme/timezone/time_format/refresh_rate/reset_hour/view/custom_limit_tokens写入临时文件后replace原子落盘。主题不再被覆盖#102/#200显式选择的light/dark/classic主题跨运行保留不被背景自动检测静默替换持久化时若用户意图是auto则保存auto而非解析后的 light/dark保证下次启动继续自动检测见load_with_last_used()。Python 版本检查真正接入启动流程#172运行于 Python 3.9 以下时打印清晰的 Python 3.9 is required 消息含uv安装提示uv tool install claude-monitor --python 3.12替代晦涩崩溃。实现为validate_cli_environment()见 src/claude_monitor/cli/main.py在main()中于任何重活之前执行。2.8 其他新开关与边界约定--hide-model-distribution#161隐藏 live 视图中的模型分布条。--no-header/--no-emoji#57隐藏头部横幅 / 无 emoji 纯文本渲染。Team 计划标签与实验性 API#195/#202/#193/#157--plan team作为未验证估算标签被接受并附指引优先使用官方 statusline 数据或--plan custom--api启用实验性的 Anthropic OAuth 用量读取器TTL 缓存 Retry-After 退避默认 TTL 180 秒--api-cache-file默认~/.claude-monitor/api/latest.json。实验性 API 限额标记confidence: experimental永远不会覆盖新鲜官方 statusline 限额。适配器边界#219 等README 现在展示 Awesome Claude Code 徽章明确外部伴生工具应消费--write-state/--once --output json提供方适配器必须使用独立的source.kind禁止把非 Claude 数据自动并入 Claude 5 小时订阅窗口Cursor 与 Claude Desktop 因缺乏本地用量/限额信号而被划为 out of scope除非未来暴露类似信号。三、3.x 时代架构重构与视图体系3.1 v3.0.0从单文件到模块化包Breaking Changes3.0.0 是承上启下的架构版本包名从claude-usage-monitor更名为claude-monitor新安装命令为pip install claude-monitor或uv tool install claude-monitor命令别名claude-monitor与cmonitor。Python 最低版本从 3.8 提升到 3.9。从单文件claude_monitor.py重写为src/claude_monitor/模块化结构8 个专职模块cli/CLI 与引导、core/业务逻辑、模型、设置、计算、定价、data/数据管理、分析、读取、monitoring/实时会话监控与编排、ui/UI 组件、布局、显示控制、terminal/终端管理与主题、utils/格式化、通知、时区、模型工具。模块执行入口为claude_monitor.__main__:main——当前仓库结构完全对应这一设计。引入 Pydantic 类型安全UsageEntry、SessionBlock、TokenCounts等数据模型、Rich 终端 UI语义色进度条 、P90 分位预测、计划自动检测、线程化编排核心依赖加入pydantic2.0.0、numpy1.21.0、sentry-sdk1.40.0、pyyaml6.0rich升到13.7.0pytz升到2023.3。构建系统从 Hatchling 迁移到 Setuptools src 布局CI 恢复多 Python3.9-3.12测试、Ruff 静态检查、OIDC 可信 PyPI 发布。3.2 v3.1.0--view时间聚合视图--view realtime默认实时监控秒级更新。--view daily日级 token 用量聚合表格用于发现每日峰值时段。--view monthly月度聚合用于长期趋势与预算分析。日/月视图的表格参数在 4.0.0 中得到进一步丰富--date-format如%d.%m.%Y、--abbreviate-tokens缩写 token 数、--sparklines仅显式开启时显示迷你趋势图。表格渲染由TableViewsController完成聚合逻辑走UsageAggregatorsrc/claude_monitor/data/aggregator.py会透传时区与reset_hour。四、v2.0.0智能主题系统2.0.0 建立了为不同终端环境自动选择最佳配色的主题体系多方法主题检测ThemeDetector综合终端环境、系统设置、背景色查询OSC 转义序列判断亮/暗平台覆盖 macOS、Windows、Linux支持 VSCode 集成终端、iTerm2、Windows Terminal--theme light/dark/auto手动覆盖--theme-debug排查检测过程。三档进度条配色绿色0-49%安全、黄色50-89%接近限额、红色90-100%临界时间进度条统一蓝色燃烧速率用 emoji 反馈➡️⚡。Rich 主题集成dark 主题为暗背景优化亮色light 主题为亮背景优化深色自动探测终端能力truecolor / 256 色 / 8 色。破坏性变更进度条颜色改用语义色名cost.low/cost.medium/cost.high。在 4.0.0 中该体系进一步演进——显式主题不再被自动检测覆盖主题枚举扩展为light/dark/classic/auto见 src/claude_monitor/terminal/themes.py。五、v1.x早期实用主义演进1.x 阶段的变更记录展示了工具从能用走向好用的过程1.0.6现代 Python 打包pyproject.toml hatchling、控制台入口claude-monitor、uv推荐安装、Ruff pre-commit、CLAUDE.md 文档、终端输入刷新与清理修复避免监控期间输入损坏、CtrlC 光标恢复、退出恢复终端设置。1.0.7 / 1.0.8自动安装 Node.js /npx的依赖初始化逻辑。1.0.11放弃复杂的自动安装改为显式依赖检查check_dependency.py的test_node()/test_npx()改善 Node.js/npx 缺失时的报错信息。1.0.16修复 CtrlC 时UnboundLocalError提前初始化颜色变量给 ccusage 子进程调用加 30 秒超时防挂死启动时预检 ccusage 可用性兼容 npm 7npx 找不到全局包的问题双路命令执行——先试直接ccusage失败回退npx ccusage并报告实际使用的执行方式。1.0.17启动即显示加载屏消除黑屏体验加载期间显示头部横幅与 Fetching Claude usage data...。1.0.19时区处理锁定到 Europe/Warsaw 计算、显示时区与重置时间计算分离简化 reset 时间逻辑。这些早期修复为 3.0.0 的重写积累了明确的痛点清单依赖脆弱、终端处理不当、黑屏体验、时区混乱——后来的模块化架构几乎逐一回应了它们。六、如何验证这些变更测试与源码阅读路径CHANGELOG 中几乎所有条目都能在当前仓库找到对应实现与回归测试测试位于 src/tests主题实现位置相关测试官方限额信任层src/claude_monitor/output/official.pytests/test_snapshots_official.py、tests/test_live_official_overlay.py快照协议与退出码src/claude_monitor/output/snapshots.pytests/test_snapshots.py、tests/test_api_usage.py状态文件原子写入src/claude_monitor/output/state.pytests/test_state.py仓库与报表src/claude_monitor/data/warehouse.py、src/claude_monitor/data/reports.pytests/test_warehouse.py、tests/test_warehouse_reports.py计划与 P90 限额src/claude_monitor/core/plans.py、src/claude_monitor/core/p90_calculator.pytests/test_calculations.py、tests/test_analysis.py定价修正src/claude_monitor/core/pricing.pytests/test_pricing.py时区与重置语义src/claude_monitor/utils/timezone.py、src/claude_monitor/data/aggregator.pytests/test_timezone.py、tests/test_time_utils.pyCLI 引导与路径发现src/claude_monitor/cli/main.pytests/test_cli_main.py、tests/test_cli_bootstrap.py、tests/test_wsl_paths.py设置持久化src/claude_monitor/core/settings.pytests/test_settings.py想快速体验 4.0.0 的核心能力安装后uv tool install claude-monitor可直接运行# 一次性 JSON 快照含 source/confidence/provenance 字段 claude-monitor --once --output json # 单行状态输出适合 tmux 状态栏 claude-monitor --once --compact # 持续原子写入状态文件供外部工具轮询 claude-monitor --write-state --state-file ~/.claude-monitor/state/latest.json # 作为 Claude Code statusline 钩子捕获官方 rate_limits claude-monitor --statusline # 开启持久化仓库并按需导出报表 claude-monitor --warehouse claude-monitor --warehouse --view sessions --output csv claude-monitor --warehouse --view burn-rate --output csv # 多数据源扫描 仅统计 Claude 模型 claude-monitor --data-paths ~/.claude/projects --data-paths ~/.config/claude/projects --filter-models anthropic七、总结从 CHANGELOG 可以清晰看到 claude-monitor 的三次质变1.x 是能用包装外部工具、解决终端体验3.0.0 是可维护模块化、类型安全、专业打包4.0.0 是可信、可编程、可持久官方限额信任层 版本化快照协议 原子状态文件 本地仓库。对使用者而言4.0.0 带来的最实际收益是所有数字都有来源标签official/local_estimate/experimental脚本与状态栏有了稳定的机器协议历史数据不再随 Claude 的 30 天清理而丢失对开发者而言这份 CHANGELOG 配上 src/claude_monitor 的模块结构是理解限额监控工具应当如何设计信任边界与数据契约的一份高质量参考。赞分享AI 应用CLI【免费下载链接】Claude-Code-Usage-MonitorReal-time Claude Code usage monitor with predictions and warnings项目地址https://gitcode.com/gh_mirrors/cl/Claude-Code-Usage-Monitor点击查看免费下载相关推荐Gson 版本演进全解析从 1.0 到 2.10 的 CHANGELOG 深度解读Gson 版本演进全解析从 1.0 到 2.10 的 CHANGELOG 深度解读 Gson 是 Google 开源的 Java 序列化/反序列化库用于在后端visx 版本演进全解析从 v0.0.112 到 v4.0.0 的 CHANGELOG 深度解读visx 版本演进全解析从 v0.0.112 到 v4.0.0 的 CHANGELOG 深度解读 本文以 CHANGELOG.md https://link.数据可视化前端图表库iced 版本演进全解析从 0.1.0-alpha 到 0.14.0 的 Changelog 深度解读iced 版本演进全解析从 0.1.0 alpha 到 0.14.0 的 Changelog 深度解读 本篇技术指南以 iced 仓库的 CHANGELOG.前端跨平台UI组件桌面应用上一篇Windows微信批量消息自动化告别重复点击的技术实现方案下一篇探索未来编程SilQ - 高级智能合约语言创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
