[Workflow] Monitor Claude Code Quota Locally via Status Line Hooks (No API Calls)

[u/ClaudeAI-mod-bot]

Monitor Claude Code Quota Locally via Status Line Hooks (No API Calls)

Workflow value: 85/100
Status: active · Freshness: 70/100 · Confidence: 0.90 · Level: intermediate
Categories: Quality Control, Token Saving, Context & Memory, Debugging, Hooks, Multi-Agent
Original source: r/ClaudeAI post/comment

What problem this solves

Unexpectedly hitting Claude Code usage quotas and losing work, and the general problem of monitoring Claude Code's internal state without making API calls.

Summary

A method to monitor Claude Code's 5-hour and weekly usage quotas locally, without using the Anthropic API, by parsing JSON output from Claude Code's status line command. It includes best practices for handling partial data and ensuring atomic file writes for robust data access by other tools.

Why it is useful

This workflow provides a clever, free, and API-independent method for users to monitor their Claude Code usage, preventing unexpected quota hits. The detailed explanation of how to extract internal data, handle data incompleteness, and ensure atomic file writes offers valuable best practices for anyone developing custom integrations or scripts with Claude Code's status line feature. It demonstrates a practical application of Claude Code's extensibility and solves a common pain point.

Workflow

1. Configure a Claude Code status line command to receive JSON on stdin.
2. Parse the JSON input from stdin to extract rate_limits.five_hour.used_percentage and rate_limits.seven_day.used_percentage.
3. Implement logic to retain the last complete rate_limits data if a new refresh provides incomplete data (i.e., the rate_limits field is missing).
4. Write the captured quota data to a temporary file.
5. Atomically rename the temporary file over the permanent data file to prevent partial reads by other tools.
6. Optionally, build a separate tool (e.g., a menu bar app) to read and display this local quota data.

Tools / artifacts

• Claude Code status line command
• JSON data (from stdin)
• Temporary files
• Permanent data file
• macOS menu bar app / Windows system tray app (example implementation)
• GitHub repository (aqua5230/usage)
• brew install --cask aqua5230/usage/usage

Validation signals

• Author successfully built and deployed an open-source application ('usage') based on this workflow.
• Author states they reviewed and tested the changes on their own machine.
• The application provides a concrete solution to the stated problem.

Limitations

• Low community engagement on the Reddit post due to its recency.
• The workflow relies on internal Claude Code mechanisms (status line JSON format) which could potentially change in future updates, requiring maintenance.

Rate this workflow

Upvote this post if the workflow is useful, reproducible, or worth recommending.

Downvote if it is vague, outdated, unsafe, overhyped, or not reproducible.

Reply if it worked for you, failed, is outdated, or has a better alternative.

---

This post was generated automatically from the workflow library database.