Claude Code Usage

核心用法

Claude Code Usage 是一个命令行配额监控工具，专为 Claude Code 开发者设计。核心功能是实时查询并可视化展示两个关键限制窗口：

• Session（5小时窗口）：短期速率限制，高频开发时的瓶颈
• Weekly（7天窗口）：长期配额限制，影响持续使用能力

基础命令 ./scripts/claude-usage.sh 即可获取带进度条和颜色编码的直观输出。支持 --fresh 强制刷新、--json 机器可读输出、--cache-ttl 自定义缓存。

显著优点

1. 零配置即用：自动从系统钥匙链读取OAuth凭证（macOS Keychain / Linux secret-tool）
2. 智能双重监控：不仅显示当前使用率，还计算精确到分钟的剩余重置时间
3. 两种自动化方案：

4. API友好：60秒智能缓存避免频繁调用Anthropic端点
5. 状态可视化：🟢🟡🔴三色进度条，一眼识别风险等级

• Session Reminder：自调度cron链，在配额重置瞬间通知，误差<1分钟
• Reset Detection：轮询监测，适合不想依赖cron精度的场景

潜在缺点与局限性

• 平台依赖：macOS/Linux only，Windows需WSL
• 前置条件：必须已完成Claude Code CLI的OAuth授权流程
• 凭证风险：脚本需要访问系统钥匙链，虽为只读但仍属敏感权限
• 监控盲区：无法预测未来使用量，仅反映历史消耗趋势
• API稳定性：依赖未公开的 api.anthropic.com/api/oauth/usage 端点，存在变更风险

适合人群

• 重度Claude Code用户：日活开发、依赖AI辅助编码的专业开发者
• CI/CD集成者：需要在脚本中程序化检查配额的后端工程师
• 多账户管理者：同时维护多个Anthropic账户的开发者需分别配置
• 成本敏感型团队：需要监控团队级配额消耗的技术负责人

常规风险

| 风险类别 | 等级 | 说明 |

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

| 凭证泄露 | 中 | 钥匙链访问权限若被恶意脚本滥用可读取其他密码 |

| API滥用 | 低 | 高频`--fresh`调用可能触发Anthropic侧限流 |

| 通知疲劳 | 低 | 自动化监控设置不当可能导致消息轰炸 |

| 端点失效 | 中 | 非公开API可能无预警变更或废弃 |

建议：生产环境使用Session Reminder方案（精确且API调用最少），定期检查脚本更新以适配API变更。

核心用法

Claude Code Usage 是一款轻量级命令行工具，用于实时监控 Claude Code 的 OAuth API 使用配额。执行 ./scripts/claude-usage.sh 即可获取可视化进度条展示：

• 5小时会话配额：短期速率限制，适合密集编程 session
• 7天周度配额：长期使用量控制

支持 --fresh 强制刷新、--json 机器可读输出、--cache-ttl 自定义缓存时长，灵活适配脚本集成与人工查看场景。

显著优点

1. 零配置即用：自动从系统密钥链读取 Claude Code 凭证（macOS Keychain / Linux secret-tool），无需手动管理 API Key
2. 双模式监控：Session Reminder（精确到分钟）与 Reset Detection（30分钟轮询）两种自动化方案，适配不同精度需求
3. 视觉友好：Emoji 状态指示器 + 进度条 + 颜色编码（🟢绿/🟡黄/🔴红），一眼掌握配额健康度
4. 纯 Bash 零依赖：不依赖 npm/pip，仅使用系统自带的 curl，部署极简
5. 智能自调度：Session Reminder 采用"链式 cron"设计，每次提醒后自动计算下一次配额重置时间并创建新定时任务，精准无冗余

潜在局限

1. 正则解析 JSON：使用 grep/sed 而非 jq 解析 API 响应，若 Anthropic 返回格式变化可能失效（已识别为低风险）
2. 个人维护项目：开发者 RZA 为个人身份，非知名组织，长期维护稳定性存不确定性
3. 平台限制：仅支持 macOS 和 Linux，Windows 需 WSL 环境
4. API 依赖单点：完全依赖 Anthropic 官方 API 可用性，无降级方案

适合人群

• 高频使用 Claude Code 的开发者，需要避免编程中途因配额耗尽中断
• 团队管理员，需监控成员配额使用趋势
• 自动化爱好者，希望将配额状态集成到 tmux 状态栏、Waybar 等系统监控组件
• 多设备切换用户，通过 Telegram 通知跨设备同步配额重置状态

常规风险

| 风险项 | 等级 | 说明 |

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

| 凭证安全 | 低 | 仅读取系统密钥链，不落盘存储 |

| 网络传输 | 低 | HTTPS/TLS 1.2+ 加密访问官方 API |

| 临时文件 | 低 | `/tmp` 缓存仅含使用率百分比，无敏感信息 |

| 注入攻击 | 极低 | 无 eval/exec，参数解析简单可控 |

| 隐私合规 | 低 | 符合 GDPR 数据最小化原则 |

建议操作：首次使用建议运行 ./scripts/claude-usage.sh --fresh 验证凭证读取正常；若需生产环境自动化，建议改用 Session Reminder 方案以减少 API 调用频率。