claude-subscription-usage

Fetch Claude Code usage stats as JSON from the command line.

How it works

Launches Claude Code in a temporary tmux session, runs the /usage slash command, parses the output, and returns structured JSON. The session is ephemeral — no conversation is created and nothing persists.

Requirements

• tmux
• Claude Code CLI (claude), logged in with an active subscription

Usage

bash claude-subscription-usage.sh

Output:

{
  "session_used": 27,
  "session_reset": "2026-04-12T07:00:00+08:00",
  "week_used": 88,
  "week_reset": "2026-04-13T09:00:00+08:00",
  "sonnet_used": 10,
  "sonnet_reset": "2026-04-15T09:00:00+08:00"
}

Field	Description
session_used	Current session usage percentage (0-100)
session_reset	Session reset time in ISO 8601
week_used	Weekly usage across all models (0-100)
week_reset	Weekly reset time in ISO 8601
sonnet_used	Weekly Sonnet-only usage (0-100)
sonnet_reset	Sonnet weekly reset time in ISO 8601

Examples

# Pretty print
bash claude-subscription-usage.sh | jq .

# Get weekly usage percentage
bash claude-subscription-usage.sh | jq .week_used

# Use in a script
usage=$(bash claude-subscription-usage.sh)
week=$(echo "$usage" | jq .week_used)
if [ "$week" -gt 90 ]; then
  echo "Warning: weekly usage at ${week}%"
fi

Platform support

• macOS (uses date -jf for time parsing)
• Linux (uses date -d for time parsing)

Authors

• Buwei Chiu
• Claude Code by Anthropic
• Dale 🐿️ — trust dialog handling

License

MIT