claude-usage-server

A lightweight local server that polls your Claude.ai usage and exposes it via a JSON API and an embeddable widget. Useful for monitoring your session and weekly rate limits at a glance.

What it does

• Fetches your Claude.ai usage data on a configurable interval
• Caches the result in memory so the widget loads instantly
• Serves a /usage JSON endpoint for programmatic access
• Serves a /widget HTML page with animated progress bars for both your current session limit (5-hour) and weekly limit (7-day)
• Supports light and dark mode automatically

Requirements

• Python 3.10+
• A Claude.ai account (Pro or Team)

Setup

1. Clone the repo

git clone https://github.com/your-username/claude-usage-server.git
cd claude-usage-server

2. Install dependencies

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

3. Configure environment variables

Copy the example file and fill in your values:

cp .env.example .env

Variable	Required	Description
SESSION_COOKIE	Yes	Your sessionKey cookie from claude.ai
ORG_ID	Yes	Your organization ID from claude.ai
API_KEY	Yes	A secret key you choose to protect your endpoints
PORT	No	Port to run the server on (default: 5000)
REFRESH_INTERVAL	No	Seconds between usage fetches (default: 60)

Getting your SESSION_COOKIE and ORG_ID

1. Log in to claude.ai
2. Open DevTools → Application → Cookies → find sessionKey
3. For ORG_ID, open DevTools → Network, navigate to any page, and find a request to /api/organizations/... — the ID is in the URL path

Note: Your session cookie is sensitive. Never commit your .env file.

4. Run the server

python3 server.py

API

All endpoints require authentication via the API_KEY you set. Pass it as a query parameter or a header:

?key=your_api_key
# or
X-Api-Key: your_api_key

GET /usage

Returns the raw cached usage data as JSON.

{
  "data": { ... },
  "meta": {
    "last_updated": "2025-01-01T12:00:00+00:00",
    "next_refresh_in": 45,
    "refresh_interval": 60
  }
}

POST /usage/refresh

Forces an immediate re-fetch from Claude.ai, then returns the updated data in the same format as /usage.

GET /widget

Returns an HTML page with usage progress bars. Auto-refreshes on the same interval as the server. Designed to be embedded in a browser-based dashboard or as a custom widget (e.g. in Übersicht, Scriptable, or an iframe).

http://localhost:5673/widget?key=your_api_key

The widget turns amber when usage reaches 80% and supports system light/dark mode.

Project structure

.
├── server.py          # Flask server
├── public/
│   └── widget.html    # Usage widget template
├── requirements.txt
├── .env.example
└── .gitignore