claude-code-usage

核心用法

Claude Code Usage 是一款专为 Claude Code CLI 用户设计的用量监控技能，通过调用 Anthropic 官方 OAuth API ( (api.anthropic.com/api/oauth/usage) 实时获取账户的会话级（5 小时窗口）和周期级（7 天窗口）配额使用情况。用户可通过 ./scripts/claude-usage.sh 快速查看可视化进度条，或使用 --json 获取结构化数据便于集成。技能支持智能缓存（默认 60 秒）避免 API 滥用，并提供 --fresh 强制刷新选项。

核心工作流为：从系统钥匙串（macOS Keychain 或 Linux secret-tool）安全提取 OAuth Token → 向 Anthropic 发起只读查询 → 解析 five_hour 与 seven_day 利用率 → 计算重置倒计时 → 以 emoji 进度条或 JSON 格式呈现。此外，技能内置两套自动化监控方案：Session Reminder 通过自调度 cron 链在配额重置的精确时刻推送通知；Reset Detection 则通过轮询检测用量骤降触发提醒。

显著优点

1. 安全凭证管理：全程依赖操作系统级密钥存储，Token 不落盘、不硬编码，杜绝凭证泄露风险。
2. 零侵入只读设计：仅查询 /api/oauth/usage 端点，无写操作、无数据修改权限，攻击面极小。
3. 开发者友好输出：彩色进度条配合 🟢🟡🔴 状态指示器，一眼识别用量健康度；JSON 模式便于与状态栏、监控系统等工具链集成。
4. 智能自动化：自调度 cron 链实现"设置即遗忘"，无需手动维护提醒任务，且能自适应实际使用模式漂移。
5. 跨平台兼容：原生支持 macOS 与 Linux，自动适配不同凭证后端。

潜在缺点与局限性

1. 硬编码通知目标：monitor-and-notify.sh 中 Telegram target ID 固定为作者账号，用户需手动修改才能接收个人通知。
2. JSON 解析健壮性不足：依赖 grep/sed 而非 jq 等专用工具解析 API 响应，极端情况下可能解析失败。
3. 缓存目录权限：临时文件存放于 /tmp 全局可写目录，虽无敏感数据，但存在被恶意替换的理论风险。
4. 生态依赖单一：仅服务于 Claude Code CLI 用户，无法覆盖 Anthropic API 直接调用或其他 AI 平台场景。
5. 通知渠道有限：当前仅支持 Telegram（通过 clawdbot），缺乏 Slack、邮件、Webhook 等主流企业通知方式。

适合的目标群体

• 高频 Claude Code 用户：日活开发者需实时掌握配额余量，避免关键编码时段触顶。
• 团队技术负责人：需监控成员用量分布，合理规划 AI 资源分配。
• 自动化工作流构建者：希望将用量数据接入现有监控大盘（Grafana、Datadog 等）的 DevOps 工程师。
• 成本敏感型个人开发者：通过周期级用量追踪，优化调用策略以控制订阅成本。

使用风险

• API 可用性依赖：Anthropic 服务端故障或 OAuth Token 过期将导致查询失败，需定期验证凭证有效性。
• Cron 任务累积：若 Session Reminder 的自动调度逻辑异常，可能产生冗余定时任务，建议定期审计 crontab -l。
• 网络环境限制：企业防火墙若拦截 api.anthropic.com，技能将完全失效，需提前确认出站规则。
• 缓存数据滞后：默认 60 秒缓存可能导致高频场景下数据非实时，关键决策前务必使用 --fresh 强制刷新。