Add machine-readable usage output (e.g. claude usage --json)

Resolved 💬 2 comments Opened May 24, 2026 by aac Closed May 28, 2026

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-message cost_usd but not the plan limits or server-side usage percentages.
  • There's no CLI subcommand like claude usage that 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.

View original on GitHub ↗

This issue has 2 comments on GitHub. Read the full discussion on GitHub ↗