[FEATURE] Programmatic access to usage data for scheduled automation (claude --status --json)

[martymcenroe]

Preflight Checklist

• I have searched existing requests and this feature hasn't been requested yet
• This is a single feature request (not multiple features)

Problem Statement

I've built a Windows Task Scheduler system running Claude Code via claude -p for:

• Hourly heartbeat to anchor usage windows
• Daily deep audits at 4:30 AM
• Batch audit jobs during idle hours

This maximizes my $100/month Max subscription by running heavy workloads during sleep hours and anchoring reset windows to predictable times.

The problem: I can schedule claude -p "/audit 0817" and it works beautifully. But I cannot:

• Query current 5-hour window usage %
• Query weekly usage %
• Get reset times programmatically
• Log which model served the request

The /status command shows all this but only works interactively.

Proposed Solution

Either:

1. claude --status --json - CLI flag that outputs usage JSON
2. Add usage fields to statusLine JSON input (per Feature Request: Include usage data in status line JSON input #8412)
3. claude usage --json - Subcommand for usage data

Sample Output Desired:

{
  "model": "claude-opus-4-5-20251101",
  "five_hour_window": {
    "percent_used": 4,
    "resets_at": "2026-01-07T14:00:00-06:00"
  },
  "weekly_window": {
    "percent_used": 82,
    "resets_at": "2026-01-08T02:00:00-06:00"
  },
  "sonnet_weekly": {
    "percent_used": 2,
    "resets_at": "2026-01-13T16:00:00-06:00"
  }
}

Alternative Solutions

• Tried claude -p "/status" - does not work
• Tried echo "/status" | claude -p - does not work
• No HTTP API endpoint available
• claude usage has no JSON output flag
• No cached usage file accessible
• Usage data only available via interactive /usage or /status

Priority

High - Significant impact on productivity

Feature Category

CLI commands and flags

Use Case Example

1. Windows Task Scheduler runs claude-heartbeat.ps1 every hour at :01
2. Script runs claude --status --json to get current usage
3. If 5-hour window > 90%, script logs warning and defers heavy jobs
4. If weekly window resets within 2 hours, script queues batch jobs
5. Results logged to claude-heartbeat.log (14-day rolling)
6. Daily audit at 4:30 AM checks logs, optimizes next day's schedule

Additional Context

Related issues:

• Make /status and/or login account checkable from command line #1886 - Make /status checkable from command line (at risk of auto-close)
• Feature Request: Include usage data in status line JSON input #8412 - Include usage data in status line JSON input (at risk of auto-close)

My automation setup:

$trigger = New-ScheduledTaskTrigger -Daily -At "04:30"
$action = New-ScheduledTaskAction -Execute "powershell.exe" -Argument "-WindowStyle Hidden -NoProfile -ExecutionPolicy Bypass -File C:\Users\mcwiz\Projects\claude-daily-audit.ps1"
Register-ScheduledTask -TaskName "Claude-DailyAudit" -Trigger $trigger -Action $action

This is missing one piece: programmatic usage data to make intelligent scheduling decisions.

Why this matters for Max subscribers doing serious automation:

1. Know when to schedule heavy jobs (after reset)
2. Track usage patterns over time
3. Avoid hitting limits during critical work
4. Build dashboards/alerts for team usage

I'm willing to contribute code if someone can point me to where /status gets its data and how the CLI arg parsing works.

[github-actions]

Found 3 possible duplicate issues:

1. Feature Request: Include usage data in status line JSON input #8412
2. Feature Request: Expose usage quota in status line JSON #15844
3. Add Quota Information Access to Claude Code CLI #13585

This issue will be automatically closed as a duplicate in 3 days.

• If your issue is a duplicate, please close it and 👍 the existing issue instead
• To prevent auto-closure, add a comment or 👎 this comment

🤖 Generated with Claude Code