Feature Request: Expose subscription usage data via local file or API

Summary

Provide a way for users and tools to programmatically access Claude Code Pro/Max subscription usage data (session and weekly quota percentages, reset times).

Problem

Currently, the only way to check subscription usage is via the /usage command, which:

Displays data in the terminal but doesn't expose it programmatically
Fetches from Anthropic's servers but doesn't cache locally
Cannot be invoked by external tools or scripts

This makes it impossible to build companion tools that help users:

Monitor usage in real-time
Get alerts before hitting limits
Track usage patterns over time
Plan sessions efficiently

Proposed Solution

One or more of the following:

Option A: Local cache file

Write usage data to a local file (e.g., ~/.claude/usage-cache.json) after each /usage call or periodically:

{
  "session": {
    "percentUsed": 59,
    "resetIn": "2h 47m",
    "resetAt": "2026-01-30T15:30:00Z"
  },
  "weekly": {
    "percentUsed": 29,
    "resetDay": "Wednesday",
    "resetAt": "2026-02-05T11:29:00Z"
  },
  "updatedAt": "2026-01-30T12:43:00Z"
}

Option B: Machine-readable `/usage` output

Add a flag like /usage --json that outputs structured data instead of formatted text.

Option C: Include in stats-cache.json

Extend the existing ~/.claude/stats-cache.json to include current quota status.

Use Cases

CLI companion tools - Build dashboards showing real-time usage
Alerts - Get notified before hitting session/weekly limits
Planning - Tools that help distribute usage across the week
Automation - Scripts that pause work when approaching limits

Current Workaround

Users must manually read /usage output and input numbers into external tools - this is error-prone and tedious.

Additional Context

The API already returns rate limit headers (anthropic-ratelimit-*) for per-minute limits. Extending this pattern to subscription quotas would be consistent and helpful.

Related: The existing stats-cache.json already tracks token usage but lacks quota context.

Found 3 possible duplicate issues:

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

Strong +1 for this feature request.

I maintain CodexBar, a macOS menu bar app that displays Claude Code usage. Currently, we face a significant UX problem that this feature would solve.

The Problem

On macOS, Claude Code stores OAuth credentials in the Keychain. Third-party apps like CodexBar need these credentials to fetch usage data from the API. However:

Keychain ACL resets on token refresh - When Claude CLI updates the token, the Access Control List is reset, revoking CodexBar's access
Users see repeated keychain prompts - Multiple times per day, users must enter their login password to allow CodexBar to access the credential
There's no workaround - On macOS, Claude Code doesn't write credentials to ~/.claude/.credentials.json (only Linux does)

See related issue #19456 which documents the keychain ACL problem.

Why Usage Cache Solves This

If Claude Code wrote usage data to a cache file:

Third-party tools would not need credential access at all
No keychain prompts ever
Claude Code (which owns the keychain item) fetches data and writes to cache
Third-party tools simply read the cache file

This is the cleanest architectural solution because:

No credential sharing between apps
No security concerns about token exposure
Follows the principle of least privilege
Benefits the entire ecosystem of third-party tools

Proposed Cache Location

~/.claude/usage-cache.json

Minimal Viable Schema

{
  "session": {
    "percentUsed": 42.5,
    "resetsAt": "2026-01-31T15:00:00Z"
  },
  "weekly": {
    "percentUsed": 28.0,
    "resetsAt": "2026-02-05T00:00:00Z"
  },
  "updatedAt": "2026-01-31T10:30:00Z"
}

Implementation Suggestion

Write/update the cache file whenever:

User runs /usage command
Claude Code refreshes the OAuth token (since it's already making API calls)
Optionally: periodic background refresh during active sessions

Even just option 1 would be valuable - users could run /usage occasionally and third-party tools would read the cached data.

Affected Third-Party Tools

CodexBar - macOS menu bar usage display
Potentially others building usage monitoring tools

Would love to see this prioritized given the current keychain UX issues on macOS.

+1 — this shouldn't have been marked as a duplicate. The core ask (expose subscription usage programmatically) is distinct from generic "analytics" requests. The data is already fetched for /usage — caching it locally or piping it into the statusline hook would be a small implementation with huge user impact. 8+ open issues requesting the same thing speaks for itself.

+1 for this one. Or add ability to fetch that data via API

+1 - would also love to see this available to the data provided to the statusline tool - would love to track my session usage in my status line.

Add workflow to track anthropics/claude-code#21943

this script works as a status line which includes quota data: https://github.com/slopware/claude-quota

this script works as a status line which includes quota data: https://github.com/slopware/claude-quota

thanks - I actually stole that logic and am using it right now - this will do for now until anthropic implements an official solution.

+1 — closed my duplicate #33215 in favor of this one.

Adding two desktop app / Cowork-specific angles not yet covered here:

1. Always-visible usage indicator in the menu bar icon
The Claude menu bar icon could visually represent usage as a fill level (like the macOS battery icon) — empty at 0%, full at 100%, with color shift (green → yellow → red). Tooltip on hover: "Session: 72% | Weekly: 45%". This gives at-a-glance awareness without opening the app.

2. MCP tool access for Cowork mode
In Cowork mode, Claude runs with MCP tools (Desktop Commander, Chrome, Gmail, GCal, scheduled tasks). Claude itself has zero visibility into its own token consumption or quota. Exposing usage via an internal MCP tool or query would let Claude:

Defer heavy tasks when quota is low ("You're at 85% — defer to next session?")
Skip scheduled tasks that would exceed remaining quota
Plan multi-step workflows against remaining capacity

Until native usage data is exposed, a PostToolUse hook can track session-level usage and write it to a local file:

INPUT=$(cat)
TOOL=$(echo "$INPUT" | jq -r '.tool_name // "unknown"' 2>/dev/null)
TS=$(date -Iseconds)
USAGE_FILE="$HOME/.claude/usage.jsonl"
echo "{\"ts\":\"$TS\",\"tool\":\"$TOOL\",\"session\":\"$$\"}" >> "$USAGE_FILE"
exit 0

USAGE_FILE="$HOME/.claude/usage.jsonl"
SUMMARY_DIR="$HOME/.claude/usage-reports"
mkdir -p "$SUMMARY_DIR"
SESSION_ID="$$"
REPORT="$SUMMARY_DIR/$(date +%Y%m%d-%H%M%S).json"
TOTAL=$(grep -c "\"session\":\"$SESSION_ID\"" "$USAGE_FILE" 2>/dev/null || echo 0)
BASH=$(grep "\"session\":\"$SESSION_ID\"" "$USAGE_FILE" | grep -c '"Bash"' 2>/dev/null || echo 0)
EDIT=$(grep "\"session\":\"$SESSION_ID\"" "$USAGE_FILE" | grep -c '"Edit"' 2>/dev/null || echo 0)
READ=$(grep "\"session\":\"$SESSION_ID\"" "$USAGE_FILE" | grep -c '"Read"' 2>/dev/null || echo 0)
jq -n --argjson total "$TOTAL" --argjson bash "$BASH" --argjson edit "$EDIT" --argjson read "$READ" \
    '{total: $total, bash: $bash, edit: $edit, read: $read, date: now | todate}' > "$REPORT"
echo "Session usage: $TOTAL calls (Bash: $BASH, Edit: $EDIT, Read: $READ)" >&2
exit 0

grep "$(date +%Y-%m-%d)" ~/.claude/usage.jsonl | wc -l
grep "$(date +%Y-%m-%d)" ~/.claude/usage.jsonl | jq -r '.tool' | sort | uniq -c | sort -rn
for i in $(seq 0 6); do
    D=$(date -d "-${i}days" +%Y-%m-%d)
    COUNT=$(grep "$D" ~/.claude/usage.jsonl 2>/dev/null | wc -l)
    echo "$D: $COUNT calls"
done

{
  "hooks": {
    "PostToolUse": [{"hooks": [{"type": "command", "command": "bash ~/.claude/hooks/usage-tracker.sh"}]}],
    "Stop": [{"hooks": [{"type": "command", "command": "bash ~/.claude/hooks/usage-summary.sh"}]}]
  }
}

This creates a local JSONL log at ~/.claude/usage.jsonl that you can query with jq, grep, or any script. Session summaries are saved to ~/.claude/usage-reports/. Not actual subscription usage, but gives you complete visibility into tool-level activity.

this is the gap between local-log tooling and server-truth quota, and it's been bugging me for months. ccusage and the monitor projects parse ~/.claude/projects/*.jsonl, which gives you token counts but not the rolling 5h or weekly window Anthropic actually enforces. /usage hits an internal endpoint (the same one claude.ai/settings/usage renders) and that's the only number that matches what gets you rate-limited. option B (--json) is the cleanest fix because the data already exists server-side, the CLI just needs to stop pretty-printing and start emitting structured output. without it everyone ends up scraping the terminal.

Here's yet another workaround to this https://github.com/hiinaspace/claude-quota . it runs an empty claude code session in screen, types in /usage, scrolls down and parses the bars into JSON on stdout. takes a bit to run since claude code startup is slow (~5 seconds) and is fragile to changes, but works in a pinch.

Just write claude "/usage" -p and parse by your tool.

QuotaTempo maintainer here. This also affects users who are signed in to Claude Desktop and actively use its Code tab, but are not signed in to the standalone Claude Code CLI. Desktop local usage history provides a recent weekly utilization sample, yet no exact next reset timestamp. A previously cached CLI reset can be joined only until that known window expires; after rollover, a companion app cannot safely derive the next exact reset from Desktop history alone.

A supported, user-consented, read-only interface returning weekly and five-hour utilization, exact reset timestamps, observation time, and a non-secret account identity would solve this without scraping the TUI or reusing browser cookies/shared OAuth credentials. It should work for Desktop-only sessions and after a weekly rollover. Related investigation: Ishikawa-Hidekazu/quota-tempo#23

I'm building Quotzii, a native macOS menu bar app that helps Claude Code users monitor their session and weekly usage limits at a glance.

Currently, Quotzii relies on usage information exposed by Claude Code. This works well for my use case, but I'd prefer not to depend on undocumented or potentially unstable behavior.

Would Anthropic consider providing a documented, machine-readable interface for retrieving subscription usage limits and reset times?

This would make it much easier for developers to build reliable integrations and usage-monitoring tools for Claude Code users.

Thanks for considering this!

Navigation Menu

Repository navigation

Feature Request: Expose subscription usage data via local file or API #21943

Summary

Problem

Proposed Solution

Option A: Local cache file

Option B: Machine-readable `/usage` output

Option C: Include in stats-cache.json

Use Cases

Current Workaround

Additional Context

The Problem

Why Usage Cache Solves This

Proposed Cache Location

Minimal Viable Schema

Implementation Suggestion

Affected Third-Party Tools

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Feature Request: Expose subscription usage data via local file or API #21943

Description

Summary

Problem

Proposed Solution

Option A: Local cache file

Option B: Machine-readable /usage output

Option C: Include in stats-cache.json

Use Cases

Current Workaround

Additional Context

Activity

github-actions commented on Jan 30, 2026

NSEvent commented on Jan 31, 2026

The Problem

Why Usage Cache Solves This

Proposed Cache Location

Minimal Viable Schema

Implementation Suggestion

Affected Third-Party Tools

BareTread commented on Feb 17, 2026

seredniy commented on Feb 18, 2026

arjunsharma commented on Feb 27, 2026

slopware commented on Mar 5, 2026

BareTread commented on Mar 6, 2026

henrikblunck commented on Mar 11, 2026

yurukusa commented on Mar 29, 2026

m13v commented on Apr 28, 2026

hiinaspace commented on Jul 3, 2026

CommanderTvis commented on Sep 12, 2026

ishikawa-h commented on Sep 27, 2026

gerritvisserNL commented on Oct 10, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions

Option B: Machine-readable `/usage` output