Claude Code 使用监视器 — 实时跟踪器避免使用配额限制

Claude Code 的隐私优先使用运维伴侣工具。它结合了 Rich 实时终端监视器、官方状态栏速率限制、机器可读的状态/导出输出、来源标签、预测和可选的本地使用仓库。

🚀 安装 ⚡ 使用 uv 的现代安装方式（推荐） 📦 使用 pip 安装 🛠️ 其他包管理器

⚡ 使用 uv 的现代安装方式（推荐）

为什么 uv 是最佳选择：

✅ 自动创建隔离环境（无系统冲突）

✅ 没有 Python 版本问题

✅ 没有"externally-managed-environment"错误

✅ 简单的更新和卸载

✅ 适用于所有平台

安装和使用监视器的最快和最简单的方式：

# 使用 uv 直接从 PyPI 安装（最简单）
uv tool install claude-monitor

# 从任何地方运行
claude-monitor  # 或简写 cmonitor、ccmonitor

# 从源代码克隆和安装
git clone https://github.com/Maciek-roboblog/Claude-Code-Usage-Monitor.git
cd Claude-Code-Usage-Monitor
uv tool install .

# 从任何地方运行
claude-monitor

如果您还没有安装 uv，可以用一个命令获取：

# 在 Linux/macOS 上：
curl -LsSf https://astral.sh/uv/install.sh | sh

# 在 Windows 上：
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

# 安装后，重新启动您的终端

📦 使用 pip 安装

# 从 PyPI 安装
pip install claude-monitor

# 如果找不到 claude-monitor 命令，请将 ~/.local/bin 添加到 PATH：
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc  # 或重新启动您的终端

# 从任何地方运行
claude-monitor  # 或简写 cmonitor、ccmonitor

⚠️ PATH 设置：如果看到警告：脚本 claude-monitor 已安装在 '/home/username/.local/bin'，不在 PATH 上，请按照上面的 export PATH 命令操作。

⚠️ 重要提示：在现代 Linux 发行版（Ubuntu 23.04+、Debian 12+、Fedora 38+）上，您可能会遇到"externally-managed-environment"错误。我们强烈建议不使用 --break-system-packages，而是：

使用 uv 代替（见上文）- 更安全、更简单

使用虚拟环境 - python3 -m venv myenv && source myenv/bin/activate

使用 pipx - pipx install claude-monitor

有关详细解决方案，请参阅故障排除部分。

🛠️ 其他包管理器

# 使用 pipx 安装
pipx install claude-monitor

# 从任何地方运行
claude-monitor  # 或简写 claude-code-monitor、cmonitor、ccmonitor、ccm

# 在 conda 环境中使用 pip 安装
pip install claude-monitor

# 从任何地方运行
claude-monitor  # 或简写 cmonitor、ccmonitor

# 显示帮助信息
claude-monitor --help

该工具可以使用以下任何命令调用：

claude-monitor（主要）

claude-code-monitor（全名）

ccmonitor（短别名）

监视器自动保存您的偏好设置，避免每次运行时重新指定：

主题偏好设置 (--theme)

时区设置 (--timezone)

时间格式 (--time-format)

刷新率 (--refresh-rate, --refresh-per-second)

重置小时 (--reset-hour)

自定义令牌限制 (--custom-limit-tokens)

配置位置：~/.claude-monitor/last_used.json

# 首次运行 - 指定偏好设置
claude-monitor --plan pro --theme dark --timezone "America/New_York"

# 后续运行 - 偏好设置自动恢复
claude-monitor --plan pro

# 覆盖此会话的保存设置
claude-monitor --plan pro --theme light

# 清除所有保存的偏好设置
claude-monitor --clear

✅ 会话之间的自动参数持久化

✅ CLI 参数始终覆盖保存的设置

✅ 原子文件操作防止损坏

✅ 如果配置文件损坏，优雅地回退

✅ 计划在会话之间保存和恢复（随时用 --plan 覆盖）

✅ 显式选择的主题被保留，不会被自动检测覆盖

# 默认值（自定义计划，自动检测）
claude-monitor

# 替代命令
claude-code-monitor  # 完整描述名称
cmonitor             # 短别名
ccmonitor            # 短别名
ccm                  # 最短别名

# 退出监视器
# 按 Ctrl+C 优雅退出

如果从源代码运行，请从 src/ 目录使用 python -m claude_monitor。

机器可读使用协议

当另一个工具需要当前使用情况而无需解析 Rich TUI 时，使用这些接口：

# 一次性 JSON 快照，包含 source/confidence/provenance 字段
claude-monitor --once --output json

# 紧凑单行状态输出
claude-monitor --once --compact

# 为状态栏和仪表板保持原子写入的状态文件最新
claude-monitor --write-state --state-file ~/.claude-monitor/state/latest.json

# 安装为 Claude Code 状态栏钩子以捕获官方速率限制
claude-monitor --statusline

--once 以自动化友好的代码退出：0 表示正常、10 表示接近限制、11 表示命中限制、20 表示不确定/无活跃会话，以及 30 表示无数据或配置错误。当官方状态栏数据是新鲜的时，它获胜；否则快照回退到标记的本地估计值。

持久化使用仓库

仓库是可选的且仅限本地。它按来源、帐户、项目、模型和天存储版本化记录，以便历史记录可以超过 Claude 的 30 天清理期。

# 开始本地持久化使用
claude-monitor --warehouse

# 将仓库支持的条目导出为 JSON
claude-monitor --warehouse --view entries --output json

# 将会话百分位数和消耗率报告导出为 CSV
claude-monitor --warehouse --view sessions --output csv
claude-monitor --warehouse --view burn-rate --output csv

配置选项

# 自定义计划，P90 自动检测（默认）
claude-monitor --plan custom

# Pro 计划（约 44,000 个令牌）
claude-monitor --plan pro

# Max5 计划（约 88,000 个令牌）
claude-monitor --plan max5

# Max20 计划（约 220,000 个令牌）
claude-monitor --plan max20

# 自定义计划，明确的令牌限制
claude-monitor --plan custom --custom-limit-tokens 100000

# 在凌晨 3 点重置
claude-monitor --reset-hour 3

# 在晚上 10 点重置
claude-monitor --reset-hour 22

# 实时监控，实时更新（默认）
claude-monitor --view realtime

# 日度令牌使用，表格格式聚合
claude-monitor --view daily

# 月度令牌使用，表格格式聚合
claude-monitor --view monthly

# 调整刷新率（1-60 秒，默认：10）
claude-monitor --refresh-rate 5

# 调整显示刷新率（0.1-20 Hz，默认：0.75）
claude-monitor --refresh-per-second 1.0

📋 默认自定义计划

自定义计划现在是默认选项，专为 5 小时的 Claude Code 会话而设计。它监控三个关键指标：

令牌使用 - 跟踪您的令牌消耗

消息使用 - 监控消息计数

成本使用 - 长时间会话中最重要的指标

自定义计划通过分析过去 192 小时（8 天）的所有会话并根据您的实际使用情况计算个性化限制来自动适应您的使用模式。这确保了针对您的特定工作流程的准确预测和警告。

---

🚀 v4.0.0 主要更新 - 使用运维伴侣

🔎 官方限制信任层 - --statusline 捕获 Claude Code 的官方速率限制；过期或失效的捕获回退到标记的本地估计值。

📦 机器可读协议 - --once、--compact 和 --write-state 都使用单一版本化的快照构建器和自动化退出代码。

🏷️ 来源标签 - 导出和显示的数字区分官方、local_estimate、experimental 和未知的信心水平。

📈 持久化使用仓库 - 可选的本地历史记录在 Claude 的 30 天清理后仍能保存，具有项目/模型/天维度和 CSV/JSON 报告。

🧭 预测和进度 - 重置感知进度、日期上下文预测、仅限官方的每周百分比和命中限制冻结行为。

🧩 多源输入 - --data-paths、CLAUDE_CONFIG_DIR 和 WSL 发现可以扫描多个目录，无需将无关帐户合并到一个 5 小时窗口中。

🖥️ Rich UI 对等性 - 实时 Rich 输出、Rich 一次性输出、紧凑输出、状态文件和导出使用相同的快照契约。

🧰 外部伴侣边界 - GUI、托盘、提供程序适配器和状态栏应使用 --write-state 或 --once --output json。

🧪 回归覆盖 - 非集成套件现在涵盖信任层、状态协议、仓库、报告、标题更新、多源路径和时区边界情况。

设置时间格式（默认自动检测）

claude-monitor --time-format 24h # 或 12h

强制使用指定主题

claude-monitor --theme dark # light、dark、classic、auto

清除已保存的配置

claude-monitor --clear

默认时区会根据系统自动检测。你可以使用任意有效时区进行覆盖：

使用美国东部时间

claude-monitor --timezone America/New_York

使用东京时间

claude-monitor --timezone Asia/Tokyo

使用 UTC

claude-monitor --timezone UTC

使用伦敦时间

claude-monitor --timezone Europe/London

启用调试日志

claude-monitor --debug

将日志写入文件

claude-monitor --log-file ~/.claude-monitor/logs/monitor.log

设置日志级别

claude-monitor --log-level WARNING # DEBUG, INFO, WARNING, ERROR, CRITICAL

P90 分析：自定义套餐根据你的使用历史进行第 90 百分位数计算

成本追踪：按模型定价，并计算缓存 token

限额检测：以 95% 置信度智能检测阈值

🚀 v4.0.0 的新增功能

当官方 Claude Code 状态行中的 rate_limits 数据足够新时，将其视为实时可信数据源。

所有非官方数值都会标注来源和置信度，不再将其直接呈现为事实。

机器端使用者可以通过 --once、--compact 和 --write-state 获得统一、稳定的快照契约。

可选择启用的数据仓库报告提供持久化历史记录、百分位数、消耗速率记录，以及明确标注为估算值的套餐建议。

进度与预测：感知重置时间的进度标签、包含日期背景的预测，以及达到限额后的冻结行为。

官方周度数据：仅根据官方状态行数据呈现七天使用百分比。

多来源路径：对多个 Claude 数据目录进行去重，并标注来源和账户。

成本分析：采用当前 Anthropic 定价，支持缓存 token，并将非 Anthropic 路由模型的定价标记为未知。

--statusline：捕获官方 Claude Code rate_limits。

--once、--compact、--output json|text|csv：适合脚本使用的快照和报告输出。

--write-state、--state-file：为配套工具生成原子状态文件。

--warehouse、--warehouse-file、--warehouse-retention-days：持久保存本地使用历史。

--data-paths：扫描多个 Claude 数据目录，同时保持各目录相互独立。

--filter-models anthropic：从 Claude 限额计算中排除经路由使用的非 Claude 模型。

--set-terminal-title、--title-format：根据快照更新终端标题。

--no-header、--no-emoji、--hide-model-distribution：用于快速浏览的显示控制选项。

v4 正式确立了供配套工具使用的快照模式和信任层语义。

软件包名称仍为 claude-monitor；依然要求 Python 3.9+。

✨ 功能及工作原理

v4.0.0 架构概览

新版本进行了全面重写，采用遵循单一职责原则（SRP）的模块化架构：

🖥️ 用户界面层

🎛️ 监控编排器

🔄 数据流：Claude 配置文件 → 数据层 → 分析引擎 → UI 组件 → 终端显示

可配置的更新间隔（1～60 秒）

高精度显示刷新率（0.1～20 Hz）

智能变更检测，以尽可能降低 CPU 使用率

采用回调系统的多线程编排

进度条：符合 WCAG 标准的配色方案，并采用经过科学计算的对比度

数据表格：支持列排序，并展示特定模型的统计数据

布局管理器：可适应终端尺寸的响应式设计

主题系统：自动检测终端背景，提供最佳可读性

实时视图（默认）：通过进度条、当前会话数据和消耗速率分析进行实时监控

每日视图：汇总每日统计数据，展示日期、模型、输入/输出/缓存 token、token 总数和成本

每月视图：提供按月汇总的数据，用于长期趋势分析和预算规划

P90 计算器：通过第 90 百分位数分析智能检测限额

消耗速率分析：分析多个会话的消耗模式

成本预测：按模型定价，并计算缓存 token

会话预测：根据使用模式预测会话何时到期

背景检测：自动判断终端主题（浅色/深色）

系统集成：自动检测时区和时间格式偏好

套餐识别：分析使用模式并推荐最合适的套餐

限额发现：扫描历史数据以找出实际 token 限额

了解 Claude 会话

Claude Code 采用 5 小时滚动会话窗口机制：

会话开始：从你向 Claude 发送第一条消息时开始

会话时长：从第一条消息起持续整整 5 小时

Token 限额：适用于每个 5 小时的会话窗口

多个会话：可以同时存在多个活跃会话

滚动窗口：其他会话仍处于活跃状态时，也可以开始新会话

会话时间表示例：上午 10:30——第一条消息（会话 A 从上午 10 点开始）下午 03:00——会话 A 到期（5 小时后）

下午 12:15——第一条消息（会话 B 从中午 12 点开始）下午 05:15——会话 B 到期（5 小时后，即下午 5 点）

监控器使用复杂的分析方法计算消耗速率：

数据收集：收集过去一小时内所有会话的 token 使用量

模式分析：识别重叠会话中的消耗趋势

速率追踪：计算每分钟消耗的 token 数量

预测引擎：估算当前会话的 token 将在何时耗尽

实时更新：随着使用模式变化调整预测结果

P90 分析：使用历史用量的第 90 百分位数

置信度阈值：限额检测准确率达到 95%

缓存支持：包含缓存创建和读取的 token 成本

模型专用：适配 Claude 3.5、Claude 4 及未来模型

技术要求

核心依赖（自动安装）

pytz>=2023.3 # 时区处理 rich>=13.7.0 # Rich 终端 UI pydantic>=2.0.0 # 类型验证 pydantic-settings>=2.0.0 # 配置管理 numpy>=1.21.0 # 统计计算 pyyaml>=6.0 # 配置文件 tomli>=1.2.0 # Python <3.11 上的 pyproject 后备支持 tzdata # Windows 时区数据 tzlocal>=5.0 # 将 Windows 本地时区解析为 IANA 时区 wcwidth>=0.2.13 # 终端显示宽度计算

推荐：Python 3.11+

已测试：Python 3.9、3.10、3.11、3.12、3.13

智能检测功能

使用默认 Pro 套餐时：

检测：监控器发现 token 使用量超过 7,000

分析：扫描之前的会话以确定实际限额

切换：自动切换到 custom_max 模式

通知：显示清晰的模式变更提示

继续：使用新的更高限额继续监控

自动检测系统会：

扫描历史记录：检查所有可用的会话区块

查找峰值：识别已达到的最高 token 使用量

验证数据：确保数据质量和时效性

设置限额：将检测到的最大值用作新限额

学习模式：适应你的实际使用能力

场景：你上午 9 点开始工作，希望 token 重置时间与你的日程保持一致。

将自定义重置时间设置为上午 9 点

./claude_monitor.py --reset-hour 9

配合你的时区使用

./claude_monitor.py --reset-hour 9 --timezone US/Eastern

让重置时间与你的工作日程保持一致

更好地规划每日 token 分配

获得可预测的会话窗口

场景：你经常工作到午夜以后，需要灵活安排重置时间。

在午夜重置，形成清晰的每日边界

./claude_monitor.py --reset-hour 0

深夜重置（晚上 11 点）

./claude_monitor.py --reset-hour 23

围绕重置时间安排高强度编码会话

使用较晚的重置时间覆盖跨午夜的工作会话

在高峰时段监控消耗速率

场景：你的 token 限额似乎会发生变化，而且不确定自己的具体套餐。

自动检测你之前达到的最高使用量

claude-monitor --plan custom_max

使用自定义调度进行监控

claude-monitor --plan custom_max --reset-hour 6

让自动检测找出你的实际限额

持续监控一周以了解使用模式

记录限额发生变化或重置的时间

场景：你需要跨不同时区工作或正在旅行。

美国东海岸

claude-monitor --timezone America/New_York

欧洲

claude-monitor --timezone Europe/London

亚太地区

claude-monitor --timezone Asia/Singapore

使用 UTC 协调国际团队

claude-monitor --timezone UTC --reset-hour 12

场景：你只想查看当前状态，不进行任何配置。

直接使用默认设置运行

claude-monitor

查看状态后按 Ctrl+C

场景：分析不同时间段内的 token 使用模式。

查看包含详细统计数据的每日用量明细

claude-monitor --view daily

分析每月 token 消耗趋势

claude-monitor --view monthly --plan max20

将每日用量数据导出到日志文件以供分析

claude-monitor --view daily --log-file ~/daily-usage.log

使用不同时区查看用量

claude-monitor --view daily --timezone America/New_York

实时：实时监控当前会话和消耗速率

每日：分析每日消耗模式并识别使用高峰日

每月：分析长期趋势并规划每月预算

## 套餐选择策略

### 从默认设置开始（推荐新用户使用）

检测 Pro 套餐并自动切换

claude-monitor

Monitor 会检测你是否超出 Pro 套餐限制

必要时自动切换到 custom_max

切换时显示通知

### 已知订阅套餐的用户

如果你确定自己使用的是 Max5

claude-monitor --plan max5

如果你确定自己使用的是 Max20

claude-monitor --plan max20

根据之前的使用情况自动检测

claude-monitor --plan custom_max

### 在会话开始时尽早启动

开始使用 Claude 时启动监控（uv 安装方式）

claude-monitor

或使用开发模式

./claude_monitor.py

从一开始就准确跟踪会话

更准确地计算消耗速率

接近限制时提前预警

### 使用现代化安装方式（推荐）

使用 uv 轻松安装和更新

uv tool install claude-monitor claude-monitor --plan max5

保持系统安装环境整洁

易于更新和维护

可在任意位置使用

### 自定义 Shell 别名（旧版设置）

添加到 ~/.bashrc 或 ~/.zshrc（仅适用于开发环境设置）

alias claude-monitor='cd ~/Claude-Code-Usage-Monitor && source venv/bin/activate && ./claude_monitor.py'

监控消耗速率变化，留意 Token 消耗的突然激增，根据剩余时间调整编码强度，并围绕会话重置时间安排大型重构

### 监控消耗速率变化

留意 Token 消耗的突然激增

根据剩余时间调整编码强度

围绕会话重置时间安排大型重构

## 策略性会话规划

## 策略性会话规划

围绕重置时间安排高强度使用

claude-monitor --reset-hour 9

在重置后安排大型任务

接近限制时处理较轻量的任务

利用多个相互重叠的会话

始终使用你实际所在的时区

claude-monitor --timezone Europe/Warsaw

准确预测重置时间

更好地规划工作日程

正确估算会话过期时间

终端设置：使用宽度至少为 80 个字符的终端；启用颜色支持以获得更好的视觉反馈（检查 COLORTERM 环境变量）；考虑使用专用终端窗口进行监控；使用支持真彩色的终端以获得最佳主题体验

使用宽度至少为 80 个字符的终端

启用颜色支持以获得更好的视觉反馈（检查 COLORTERM 环境变量）

考虑使用专用终端窗口进行监控

使用支持真彩色的终端以获得最佳主题体验

随开发会话一起启动监控（uv 安装方式）

tmux new-session -d -s claude-monitor 'claude-monitor'

或使用开发模式

tmux new-session -d -s claude-monitor './claude_monitor.py'

随时查看状态

tmux attach -t claude-monitor

多会话策略：请记住，每个会话恰好持续 5 小时；你可以同时拥有多个相互重叠的会话；请跨越会话边界规划工作

请记住，每个会话恰好持续 5 小时

你可以同时拥有多个相互重叠的会话

请跨越会话边界规划工作

## 大型项目开发

持续开发环境设置

claude-monitor --plan max20 --reset-hour 8 --timezone America/New_York

上午 8:00：获得新的 Token，开始开发主要功能

上午 10:00：检查消耗速率，调整工作强度

中午 12:00：进行监控，为下午的会话做规划

下午 2:00：进入新的会话窗口，处理复杂问题

下午 4:00：处理轻量任务，为晚间会话做准备

## 学习与实验

用于学习的灵活设置

claude-monitor --plan pro

高强度开发环境设置

claude-monitor --plan max20 --reset-hour 6

## 🔧 开发环境安装

适用于希望使用源代码进行开发的贡献者和开发者：

### 快速开始（开发/测试）

克隆仓库

git clone https://github.com/Maciek-roboblog/Claude-Code-Usage-Monitor.git cd Claude-Code-Usage-Monitor

以开发模式安装

pip install -e .

从源代码运行

python -m claude_monitor

### v4.0.0 测试功能

新版本包含一套全面的测试套件：

快照、信任层、数据仓库、UI 和时区路径共包含 700 多个非集成测试

所有组件的单元测试

端到端工作流的集成测试

包含基准测试的性能测试

用于隔离测试的模拟对象

运行测试

cd src/ python -m pytest

运行测试并生成覆盖率报告

python -m pytest --cov=claude_monitor --cov-report=html

运行指定的测试模块

python -m pytest tests/test_analysis.py -v

系统中已安装 Python 3.9+

已安装 Git，以便克隆仓库

## 虚拟环境设置

强烈建议使用虚拟环境，原因如下：

🛡️ 隔离性：保持系统 Python 环境整洁，并防止依赖冲突

📦 可移植性：可轻松在不同计算机上复现完全相同的环境

🔄 版本控制：锁定特定的依赖版本，以确保稳定性

🧹 干净卸载：只需删除虚拟环境文件夹，即可移除所有内容

👥 团队协作：所有人都使用相同的 Python 和软件包版本

如果没有可用的 venv 模块：

Ubuntu/Debian

sudo apt-get update sudo apt-get install python3-venv

Fedora/RHEL/CentOS

sudo dnf install python3-venv

macOS（通常随 Python 一起提供）

如果不可用，请通过 Homebrew 安装 Python：

brew install python3

Windows（通常随 Python 一起提供）

如果不可用，请从 python.org 重新安装 Python

安装时请务必勾选 "Add Python to PATH"

或者，也可以使用 virtualenv 软件包：

通过 pip 安装 virtualenv

pip install virtualenv

然后使用以下命令创建虚拟环境：

virtualenv venv

而不是：python3 -m venv venv

1. 克隆仓库

git clone https://github.com/Maciek-roboblog/Claude-Code-Usage-Monitor.git cd Claude-Code-Usage-Monitor

2. 创建