Add machine-readable usage output (e.g. claude usage --json)
Problem
The /usage slash command shows Max plan usage percentages (daily/weekly limits, current consumption) in interactive mode, but there's no way to access this data programmatically.
claude -p "/usage"returns only"You are currently using your subscription to power your Claude Code usage"— the percentage bars and numbers are stripped.- The local SQLite DB (
~/.claude/__store.db) tracks per-messagecost_usdbut not the plan limits or server-side usage percentages. - There's no CLI subcommand like
claude usagethat outputs structured data.
Use case
I'm building a terminal dashboard (workspace orchestrator) that shells out to claude for various operations. I'd like to show current Max plan usage (daily/weekly % consumed) alongside the workspace status — similar to what /usage shows, but in my own UI.
More generally, any tooling that wraps or orchestrates Claude Code sessions would benefit from being able to query usage programmatically — rate limiting decisions, cost dashboards, CI budget guards, etc.
Proposed solution
A CLI subcommand or flag that outputs usage data in a structured format:
# Option A: dedicated subcommand
claude usage --output-format json
# Option B: flag on existing print mode
claude -p "/usage" --output-format json
Example output:
{
"plan": "max",
"daily": {
"used_pct": 23.5,
"reset_at": "2025-05-25T00:00:00Z"
},
"weekly": {
"used_pct": 47.2,
"reset_at": "2025-05-26T00:00:00Z"
}
}
The exact schema isn't important — just having some machine-readable output that includes the plan usage percentages would unlock a lot of tooling.
This issue has 2 comments on GitHub. Read the full discussion on GitHub ↗