Feature request: CLI command to query usage/quota information

Resolved 💬 4 comments Opened Mar 4, 2026 by zylos-luna Closed Apr 2, 2026

Feature Request

Is your feature request related to a problem?

When running Claude Code in autonomous/headless environments (e.g., via tmux with a guardian process), there's no programmatic way to query usage and quota information. The /usage slash command only works inside the interactive TUI and outputs to the screen — there's no machine-readable format or CLI equivalent.

Currently, the only workaround is to use tmux capture-pane to scrape the TUI output after sending /usage, which is fragile and depends on screen rendering timing.

Describe the solution you'd like

A CLI command like:

claude usage --json

That outputs structured usage data:

{
  "session": { "percent": 42, "resets": "in 3h 15m" },
  "weekly_all_models": { "percent": 67, "resets": "2026-03-07T00:00:00Z" },
  "weekly_sonnet": { "percent": 55, "resets": "2026-03-07T00:00:00Z" }
}

This would enable:

  • Automated usage monitoring and alerting (notify owner when approaching limits)
  • Dashboard integrations for teams managing multiple Claude Code instances
  • Graceful degradation (switch to lighter models or pause non-critical tasks when quota is low)

Describe alternatives you've considered

  • tmux capture-pane scraping: Current workaround. Works but fragile — depends on render timing, screen size, and TUI layout which can change between versions.
  • Anthropic API /usage endpoint: Would also work, but a local CLI command is simpler and doesn't require API key management separate from the existing auth.

Additional context

This is particularly useful for the growing ecosystem of autonomous agent frameworks (like Zylos) that run Claude Code as a long-lived process with activity monitoring. A proper CLI interface would replace brittle screen-scraping with a stable contract.

View original on GitHub ↗

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