核心用法
claude-code-usage 是一个Shell脚本工具，用于查询Claude Code CLI的OAuth API用量限额。核心操作是通过 ./scripts/claude-usage.sh 调用，支持多种参数模式：
- 默认模式：读取60秒缓存的用量数据，快速响应
--fresh强制从Anthropic API实时拉取最新数据--json输出结构化JSON，便于脚本集成和监控--cache-ttl自定义缓存有效期
脚本自动从系统密钥链（macOS Keychain / Linux libsecret）提取OAuth令牌，调用 api.anthropic.com/api/oauth/usage 端点获取 five_hour 和 seven_day 两个维度的利用率数据。
显著优点
1. 双窗口监控：同时追踪短期会话限额（5小时滚动窗口）和长期周期限额（7天滚动窗口），覆盖Anthropic对Claude Code的两层限流策略
2. 视觉化输出：进度条+红绿灯状态指示（🟢0-50%/🟡51-80%/🔴81-100%），直观判断剩余配额健康度
3. 智能缓存机制：默认60秒TTL避免频繁API调用，既保证数据时效又防止触发额外的速率限制
4. 跨平台凭证管理：原生支持macOS Keychain和Linux secret-tool，无需手动管理access token
5. 低门槛集成：单行Shell即可嵌入dotfiles、tmux statusline或CI/CD流水线
潜在缺点与局限性
- 凭证依赖：必须预先完成Claude Code CLI的OAuth登录流程，否则直接报错
- Linux依赖项：需额外安装libsecret-tools，部分精简容器环境可能缺失
- 缓存延迟：默认60秒缓存意味着极端场景下（如刚触发限流）显示可能滞后
- 无历史趋势：仅展示当前时点利用率，不提供用量曲线或预测分析
- 平台限制：明确限定Darwin/Linux，Windows WSL未测试声明
适合人群
- 高频Claude Code用户：需要在工作前快速确认剩余配额，避免任务中途被限流中断
- 自动化运维场景：将用量检查集成到Shell环境或定时监控告警系统
- 多账户/团队协作：JSON输出便于统一汇总多个成员的用量状态
常规风险
1. 凭证泄露风险：脚本需读取系统密钥链中的OAuth token，若在共享环境执行需确保文件权限受控
2. 缓存文件权限：默认缓存写入 /tmp/claude-usage-cache，多用户服务器可能存在可读风险（建议通过环境变量自定义路径）
3. API端点依赖：Anthropic未公开文档化的内部OAuth usage端点，存在未来变更或废弃可能
4. 非官方工具：由社区/个人维护，非Anthropic官方提供，功能正确性无SLA保障