Claude Code's statusLineHook: Monitor Rate Limits Locally Without API Calls
Key Takeaways
- ▸statusLineHook enables local, real-time monitoring of Claude Code rate limits without API polling or credentials
- ▸Usage data is passed as a JSON environment variable (HOOK_STATUS_LINE) directly to shell commands
- ▸The approach eliminates network overhead, supports real-time updates, and preserves privacy by keeping data local
Summary
Anthropic has documented statusLineHook, a feature of Claude Code that allows developers to monitor API usage and rate limits in real-time without making external API calls. The feature, configured via ~/.claude/settings.json, captures rate-limit and session data as JSON and passes it to shell scripts via the HOOK_STATUS_LINE environment variable. This mechanism provides real-time visibility into session usage percentage, weekly usage percentage, context usage percentage, active model name, session cost, and reset times.
The statusLineHook approach offers substantial advantages over traditional API polling: zero network overhead, no credential requirements, real-time updates after every prompt, and enhanced privacy since usage data remains local. The feature unlocks a new class of developer tools previously impractical to build, including menu bar widgets displaying usage meters, threshold alerts that trigger notifications at specific usage levels, usage logging for session history, and automated cost tracking across sessions. Headroom, a native macOS menu bar app, exemplifies this approach by displaying session and weekly usage meters in real-time using the statusLineHook mechanism.
- The mechanism enables new classes of developer tools including ambient displays, threshold alerts, usage logging, and cost tracking
