Check your AI coding tool usage quotas from the terminal. Supports Claude Code, Codex, Gemini, GitHub Copilot, z.ai, and OpenCode Go.
$ ai-usage
Claude (oauth) [Max] user@example.com
Session (5h) 72.0% left [█████░░░░░░░░░░░░░░░] resets in 4h12m
Weekly (7d) 85.0% left [███░░░░░░░░░░░░░░░░░] resets in 132h
Codex (oauth) [Plus]
Daily 95.2% left [█░░░░░░░░░░░░░░░░░░░]
Gemini (oauth) [Free]
Per-minute 100.0% left [░░░░░░░░░░░░░░░░░░░░]
Daily 88.4% left [██░░░░░░░░░░░░░░░░░░] resets in 16h
OpenCode Go (api) [Go]
Rolling 75.0% left [█████░░░░░░░░░░░░░░░] resets in 4h12m
Weekly 60.0% left [████████░░░░░░░░░░░░]
Monthly 90.0% left [██░░░░░░░░░░░░░░░░░░]
Recommended — install with pipx for an isolated global command:
pipx install ai-usage-cliOr with pip:
pip install ai-usage-cliai-usage # all enabled providers
ai-usage -p claude # single provider
ai-usage -p claude codex # multiple providers
ai-usage -p opencode-go # OpenCode Go quota only
ai-usage -a # include disabled providers
ai-usage --json # JSON output (for scripting)
ai-usage --plain # plain text (no color, no unicode)
ai-usage | grep Claude # auto-switches to plain when piped| Provider | Credential Source |
|---|---|
| Claude Code | macOS Keychain (Claude Code-credentials) or ~/.claude/.credentials.json |
| Codex | ~/.codex/auth.json (auto-refreshes OAuth token) |
| Gemini | ~/.gemini/oauth_creds.json (auto-refreshes OAuth token) |
| GitHub Copilot | apiKey in ~/.codexbar/config.json |
| z.ai | apiKey in ~/.codexbar/config.json or Z_AI_API_KEY env var |
| OpenCode Go | opencode-go entry in $XDG_DATA_HOME/opencode/auth.json (default: ~/.local/share/opencode/auth.json) |
Provider settings are stored in ~/.codexbar/config.json. Each provider can be enabled/disabled and configured with API keys where needed.
OpenCode Go uses the credential already managed by OpenCode. Its public CLI ID is opencode-go; when CodexBar has an opencodego entry, ai-usage honors that entry's enabled flag. Without an explicit CodexBar entry, an existing OpenCode Go credential enables the provider automatically. OpenCode Go quota is independent of Codex OAuth quota and must be checked separately.
Example:
{
"providers": {
"claude": { "enabled": true },
"codex": { "enabled": true },
"gemini": { "enabled": true },
"copilot": { "enabled": false, "apiKey": "ghu_..." },
"zai": { "enabled": false, "apiKey": "..." }
}
}- macOS: Claude credentials are read from the system Keychain. All other providers use file-based credentials and work cross-platform.
- Linux: Claude credentials fall back to
~/.claude/.credentials.json. All other providers work the same as macOS.
Gemini: Token expired, refresh failed
ai-usage refreshes the Gemini token by reading the OAuth client ID/secret from the locally installed gemini CLI's oauth2.js. The resolver scans common install layouts (Homebrew, npm global, fnm/nvm, Nix) and transparently follows shell wrappers. If your install is in an unusual location, set:
export GEMINI_OAUTH_JS=/path/to/@google/gemini-cli-core/dist/src/code_assist/oauth2.jsClaude: empty plan field
The provider only fills plan when the OAuth rateLimitTier matches a known tier (max, pro, team, enterprise, free). Unknown internal tiers (e.g., default_claude_ai) are hidden rather than echoed verbatim.
- Python 3.10+
- Active credentials for the providers you want to query
终端查询 AI 编程工具配额用量。支持 Claude Code、Codex、Gemini、GitHub Copilot、z.ai、OpenCode Go。
pipx install ai-usage-cliai-usage # 查看所有已启用的 Provider
ai-usage -p claude # 只看 Claude
ai-usage -p claude codex # 看 Claude 和 Codex
ai-usage -p opencode-go # 只看 OpenCode Go
ai-usage -a # 包含未启用的 Provider
ai-usage --json # JSON 输出（适合脚本处理）
ai-usage --plain # 纯文本输出（无颜色、无 Unicode）- CodexBar — macOS menu bar app for AI coding tool usage tracking.
ai-usage-clishares the same~/.codexbar/config.jsonconfiguration and was built as a cross-platform CLI companion.