StatusLine should expose API usage/quota information in JSON input

[FutureAtoms]

Issue Type: Feature Request / Enhancement

Description: The Claude Code CLI internally tracks API usage limits and displays warnings like "Approaching usage limit • resets at 7pm" in the terminal interface. However, this usage information is not exposed through the statusLine JSON input, preventing users from displaying quota information in custom status lines.

Current Behavior:

• Claude Code tracks usage internally and shows warnings when limits are approached
• StatusLine scripts receive JSON input with workspace information but no usage data
• Users cannot display remaining quota or reset times in their custom status lines

Expected Behavior: The JSON input passed to statusLine scripts should include usage information such as: { "workspace": { ... }, "usage": { "requests_remaining": 150, "total_requests": 1000, "percentage_used": 85, "reset_time": "2024-08-12T19:00:00Z", "next_reset_human": "7pm" } }

Use Case: I want to create a custom statusLine that displays:

• Remaining token/request quota
• Time until quota reset
• Current working directory
• Git branch name

Currently, I can display the directory and git info, but not the usage data that Claude Code clearly has access to internally.

Current StatusLine Configuration:

~/.claude/statusline-command.sh shows:

Quota: N/A | Reset: N/A | [main] project-folder

Environment:

• Platform: macOS (Darwin 24.6.0)
• Claude Code version: [current version]

Additional Context: Since Claude Code already tracks and displays this usage information in its own interface, exposing it through the statusLine API would allow users to create more informative and useful custom status displays without requiring separate API calls or workarounds.

[TylerGallenbeck]

You can use this in the meantime → https://github.com/TylerGallenbeck/claude-code-limit-tracker

Obviously won't be as accurate as native support, but should get you pretty close.

[coygeek]

Hey, this is a great feature request!

Just wanted to add a bit of context from the latest docs and changelog for anyone else following this issue.

It looks like the team added session cost tracking to the statusLine input in version 1.0.85. According to the documentation (Status line configuration), the JSON input now includes a cost object:

{
  "hook_event_name": "Status",
  ...
  "cost": {
    "total_cost_usd": 0.01234,
    "total_duration_ms": 45000,
    "total_api_duration_ms": 2300,
    "total_lines_added": 156,
    "total_lines_removed": 23
  }
}

So you can get the current session's cost, which is a nice step forward. For example, in your statusline-command.sh you could add something like this (if you have jq installed):

#!/bin/bash
input=$(cat)
SESSION_COST=$(echo "$input" | jq -r '.cost.total_cost_usd')

# ... your other logic for git branch, etc. ...

printf "Session Cost: $%.4f | [main] project-folder" "$SESSION_COST"

---

That said, I think you're pointing out a good distinction between session cost (which is now available) and overall account usage/quota (which is what you're asking for). The session cost is probably tracked locally by the CLI, whereas getting the account-level quota information would likely require a separate network request to an Anthropic billing API on every status update, which they might be trying to avoid for performance reasons.

Still, having that usage object you mocked up would be fantastic for power users. It would be way more useful than just the session cost for understanding when you're about to hit a limit.

+1 from me on this idea! Hope the team considers it.

[TylerGallenbeck]

"hook_event_name": "Status", ... "cost": { "total_cost_usd": 0.01234, "total_duration_ms": 45000, "total_api_duration_ms": 2300, "total_lines_added": 156, "total_lines_removed": 23

Sweet - I didn't know some of these things existed

[bartoszwarzocha]

+1 for this feature!

I would love to have token usage percentage and rate limit reset time exposed in the statusline JSON input.

Currently, Claude Code internally tracks this information (visible in system warnings like Token usage: 28150/200000; 171850 remaining), but it's not accessible to custom statusline scripts.

Proposed addition to JSON structure:

{
  "usage": {
    "tokens_used": 28150,
    "tokens_limit": 200000,
    "tokens_remaining": 171850,
    "percentage_used": 14.08,
    "reset_at": "2025-10-15T00:00:00Z"
  }
}

This would allow users to display real-time usage information in their custom statusline,
helping them better manage their API quota without interrupting their workflow.

[xrviv]

+1 for this feature!

Being able to see weekly API usage limits and reset times in the status line would be incredibly helpful for managing quota without interrupting workflow.

Current workaround of checking /usage manually isn't ideal when you're deep in a task. Having this exposed in the statusLine JSON (like the existing cost object) would make resource management seamless.

Would love to see the usage object with:

• Weekly usage percentage (all models + Opus separately)
• Reset time
• Remaining quota

Thanks for tracking this!

[github-actions[bot]]

This issue has been inactive for 30 days. If the issue is still occurring, please comment to let us know. Otherwise, this issue will be automatically closed in 30 days for housekeeping purposes.

[HummingMind]

+1. Would be awesome to have access to this in statusline.

[kleber-maia]

+1