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

Found 3 possible duplicate issues:

1. https://github.com/anthropics/claude-code/issues/20413
2. https://github.com/anthropics/claude-code/issues/13585
3. https://github.com/anthropics/claude-code/issues/21486

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:

1. Keychain ACL resets on token refresh - When Claude CLI updates the token, the Access Control List is reset, revoking CodexBar's access
2. Users see repeated keychain prompts - Multiple times per day, users must enter their login password to allow CodexBar to access the credential
3. 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:

1. User runs /usage command
2. Claude Code refreshes the OAuth token (since it's already making API calls)
3. 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.

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.

<img width="552" height="165" alt="Image" src="https://github.com/user-attachments/assets/3240f460-2fa6-4fbf-bd86-093bb36eb43e" />

+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.