Claude Code Usage

核心用法

本技能提供 claude-usage.sh 脚本，用于查询 Claude Code OAuth API 的会话级（5 小时）和周期级（7 天）用量配额。默认读取本地缓存（60 秒 TTL）避免频繁请求 Anthropic API，支持 --fresh 强制刷新、--json 机器可读输出及自定义缓存时间。输出包含可视化进度条、颜色状态指示（绿/黄/红）及距重置的倒计时。

显著优点

1. 双窗口监控：同时覆盖短期突发（5h）与长期周期（7d）两类限流场景，防止工作中途被限流中断；
2. 零配置凭证：自动从 macOS Keychain 或 Linux secret-tool 提取 Claude Code OAuth Token，无需手动管理密钥；
3. 自动化通知：配套 monitor-usage.sh 可检测配额重置事件（用量骤降 >10% 或 <5%），并通过 Telegram 推送提醒，适合高频用户定时抢额度；
4. 可嵌入工作流：JSON 输出便于集成到状态栏、CI 脚本或监控系统。

潜在缺点与局限性

• 私有 API 依赖：直接调用 api.anthropic.com/api/oauth/usage，该端点未在官方文档公开，Anthropic 可能随时变更或关闭；
• 凭证耦合：要求本地已安装并登录 Claude Code CLI，首次使用需人工完成 OAuth 授权流；
• Linux 额外依赖：需手动安装 libsecret-tools，部分精简系统可能缺失；
• 通知渠道单一：自动监控仅支持 Telegram，无原生 macOS/Linux 桌面通知备选。

适合人群

• 重度 Claude Code 用户（每日多会话、接近额度上限）；
• 需要把 Claude Code 集成到自动化脚本或 CI/CD 的开发者；
• 习惯在终端/状态栏实时查看资源消耗的工程师。

常规风险

• 隐私泄露风险：脚本访问系统密钥链，若被篡改可能泄露 OAuth Token；建议校验脚本来源并限制文件权限（chmod 700）；
• API 滥用风险：尽管有缓存，若用户强制高频刷新（--fresh 循环调用），可能触发 Anthropic 侧限流或封禁；
• 误报风险：监控脚本基于用量骤降判断"重置"，若 Anthropic 调整限流算法或用户手动清除会话，可能产生虚假通知。

核心用法

Claude Code Usage 是一款专为 Claude Code 用户设计的配额监控工具，提供实时的使用量追踪与可视化展示。

主要功能模块：

1. 双窗口配额监控 - 同时追踪 5 小时会话窗口和 7 天周窗口的使用率
2. 智能缓存机制 - 默认 60 秒缓存避免频繁 API 调用，支持自定义 TTL
3. 多格式输出 - 文本模式（带进度条、emoji 状态）和 JSON 模式（机器可读）
4. 自动监控提醒 - v1.1.0 新增功能，每 30 分钟检测配额重置，支持 Telegram 推送

使用方法：

# 查看当前用量（优先缓存）
./scripts/claude-usage.sh

# 强制刷新数据
./scripts/claude-usage.sh --fresh

# JSON 输出供集成
./scripts/claude-usage.sh --json

技术实现：

• macOS：读取 Keychain 存储的 OAuth token
• Linux：通过 secret-tool 访问凭证存储
• 调用 Anthropic 官方 API api.anthropic.com/api/oauth/usage
• 纯 Shell 脚本实现，零第三方依赖

显著优点

| 维度 | 亮点 |

|------|------|

| **安全性** | A 级安全认证 (85/100)，使用系统凭证存储，无硬编码密钥 |

| **零依赖** | 仅使用 curl/grep/sed 等系统工具，无 npm/pip 供应链风险 |

| **可视化** | 进度条 + 颜色编码（🟢🟡🔴）直观展示用量健康度 |

| **自动化** | 内置监控脚本，配额重置自动推送通知 |

| **可集成** | JSON 输出支持管道处理，方便嵌入状态栏/监控系统 |

潜在局限

1. 平台限制：目前仅支持 macOS 和 Linux，Windows 需 WSL 环境
2. 凭证前提：必须预先完成 Claude Code CLI 的 OAuth 登录
3. 缓存权限：当前缓存文件使用默认权限，建议手动加固为 600
4. 网络依赖：无离线模式，API 不可用时无法查看历史数据
5. 解析健壮性：部分 JSON 解析使用 grep/sed，极端情况下可能需 jq 辅助

适合人群

• Claude Code 重度用户：需要时刻关注配额避免中断工作流
• 团队管理员：监控团队成员用量，合理分配资源
• 自动化爱好者：可将 JSON 输出接入现有监控体系（如 Prometheus + Grafana）
• 效率工具玩家：喜欢命令行工具与状态栏集成的开发者

常规风险

| 风险项 | 等级 | 说明 |

|--------|------|------|

| 外部 API 访问 | 🟡 低 | 仅访问 Anthropic 官方端点，TLS 加密传输 |

| 凭证读取 | 🟢 低 | 使用系统安全存储，符合最佳实践 |

| 缓存泄露 | 🟢 低 | 缓存仅含百分比数据，无敏感信息 |

| 供应链攻击 | 🟢 极低 | 零第三方依赖，攻击面极小 |

来源可信度：T2 等级（GitHub 个人开发者 azaidi94，代码完全开源可审计）

改进建议：采纳安全报告中的 4 项建议（缓存权限、速率限制、超时设置、jq 增强）后可提升至 S 级。