>_ resources

Claude Limits Monitor

A multi-platform monitoring system that tracks your Claude.ai usage limits in real-time — from your macOS menu bar, Chrome extension, iOS home screen, and Apple Watch.

Chrome Extension + Node.js Bridge + Express API + SwiftBar + SwiftUI · 5 platforms, one data pipeline

macOS menu bar
🕑 Session 72%|☀️ Daily 45%|🗓️ Weekly 38%|📆 Monthly 22%
chrome extension popup
Session
██████████████░░░░░░72%
↻ 2h 14m
Daily
█████████░░░░░░░░░░░45%
↻ 8h 02m
Weekly
████████░░░░░░░░░░░░38%
↻ 3d 4h
Monthly
████░░░░░░░░░░░░░░░░22%
↻ 18d
Opus
█████████████████░░░85%
Sonnet
██░░░░░░░░░░░░░░░░░░12%
Bridge: connectedLast updated 12s ago
ArchitectureComponentsMetricsInstallation

>_Architecture

data flow
  Chrome Extension (claude.ai/settings/usage)
    │  intercepts fetch/XHR + scrapes DOM
    ▼
  Local Bridge (localhost:19876)
    ├─▸ ~/.claude-limits/usage.json
    ├─▸ ~/.claude-limits/history.jsonl
    ├─▸ SwiftBar Plugin (polls /status)
    └──▸ forwards to ▼
  Cloud API (Express + SQLite)
    ├─▸ usage_snapshots table
    ├─▸ alert rules (push notifications)
    └─▸ iOS App + Widget + watchOS

Local-First Design

The system works entirely offline. The Chrome extension captures data, the local bridge persists it, and the SwiftBar plugin reads from the bridge. The cloud API is optional — only needed for iOS/watchOS sync and push notifications.

Dual Capture Strategy

The extension uses two content scripts. The interceptor.js runs in MAIN world to hook into fetch() and XMLHttpRequest, catching API responses as they arrive. The content.js runs in ISOLATED world as a fallback, scraping usage percentages directly from the DOM.

Auto-Refresh Loop

The extension automatically refreshes the settings page every 90 seconds by clicking the “Last updated” button. The background service worker syncs with the bridge every 60 seconds and force-rescrapes every 90 seconds. Data is always fresh without manual intervention.

>_Components

Five interconnected components form a pipeline from data capture to display. Each can run independently or together for the full experience.

🌍

Chrome Extension

MV3 + Interceptor

Runs two content scripts on claude.ai — one in MAIN world to intercept fetch/XHR API responses, another in ISOLATED world to scrape the settings page DOM. Auto-refreshes every 90 seconds to catch limit changes. Badge shows max usage % with color-coded alerts.

🌐

Local Bridge

localhost:19876

Node.js HTTP server that receives usage data from the extension, persists snapshots to ~/.claude-limits/usage.json, and appends time-series history to a JSONL file. Auto-starts on macOS login via LaunchAgent.

☁️

Cloud API

Express + SQLite

REST API with JWT auth and better-sqlite3 (WAL mode). Stores usage snapshots, serves historical data, handles push notification registration, and processes alert rules like "notify if weekly > 80%".

📊

Menu Bar Plugin

SwiftBar/xbar

Python 3 script that polls the bridge every 5 minutes. Shows top 2 metrics in the macOS menu bar with emoji indicators. Dropdown reveals all metrics with color-coded progress bars and reset countdowns.

📱

iOS + watchOS Apps

SwiftUI

Native SwiftUI app (iOS 17+, watchOS 10+) with home screen widget and watch complications. Connects to the cloud API for multi-device sync. Glanceable usage at a glance from any Apple device.

>_Metrics Tracked

Every metric is color-coded: green (<70%), amber (70-89%), and red (≥90%). Here is what each one tracks:

🕑

Session

72%

Current 5-hour session usage. Resets automatically. The most volatile metric — can spike quickly during heavy usage.

☀️

Daily

45%

Daily usage quota. Resets at midnight UTC. Most relevant for pacing your work throughout the day.

🗓️

Weekly

38%

Rolling 7-day usage window. Includes absolute used/total counts when available from the API response.

📆

Monthly

22%

Monthly billing cycle usage. The long-horizon view for budget planning.

✦

Per-Model

Opus 85% / Sonnet 12%

Individual usage breakdown for Opus, Sonnet, and Haiku. Helps identify which model is consuming your quota fastest.

↻

Reset Timers

2h 14m

Countdown until each limit resets. Extracted from API responses so you know exactly when capacity frees up.

>_Installation

1. Download the Chrome extension

Download the extension package and unzip it to a permanent location on your machine:

claude-limits-extension.zip~10 KB
# Or via terminal:
mkdir -p ~/claude-limits-extension
cd ~/claude-limits-extension
curl -fsSL https://raba.pl/claude-limits-extension.zip -o extension.zip
unzip -o extension.zip && rm extension.zip

2. Open Chrome Extensions page

Navigate to chrome://extensions in your browser. Toggle “Developer mode” on (top-right corner).

⚙️
chrome://extensions → Developer mode ON

3. Load the extension

Click “Load unpacked” and select the folder where you unzipped the extension (e.g. ~/claude-limits-extension). The extension icon will appear in your toolbar.

4. Visit your Claude usage page

Go to claude.ai/settings/usage — the extension will start capturing your limits immediately. Click the extension icon to see your current usage.

Tip: Keep the usage page open in a tab. The extension auto-refreshes every 90 seconds so your data stays current without any manual action.

5. Optional: Local bridge for menu bar

For the macOS menu bar widget and data persistence, install the local bridge server:

git clone https://github.com/Rabusek/claude-limits.git
cd claude-limits
bash setup.sh

This creates ~/.claude-limits/, installs the bridge as a macOS LaunchAgent (auto-starts on login), and copies the SwiftBar plugin.

Extension contents

claude-limits-extension/
├── manifest.json      # Chrome MV3 manifest
├── background.js      # Service worker (badge, bridge sync, alarms)
├── interceptor.js     # MAIN world — intercepts fetch/XHR
├── content.js         # ISOLATED world — DOM scraper fallback
├── popup.html         # Extension popup UI
└── popup.js           # Popup controller (renders limit cards)

>_Tech Stack

LayerTechnologies
Chrome ExtensionJavaScript (Manifest V3), Chrome Storage API, message passing
Bridge ServerNode.js, native HTTP module, JSONL storage
Cloud APIExpress.js, better-sqlite3 (WAL), JWT, nanoid
Menu BarPython 3, urllib, SwiftBar/xbar
MobileSwiftUI (iOS 17+, watchOS 10+), WidgetKit, Xcode 16
DataLocal JSON + JSONL files, SQLite WAL database
← back to raba.pl