TokenWatch
Self-hosted API quota & token limit tracker with live dashboard, 7-day history charts, and ntfy alerts.
Overview
TokenWatch is a self-hosted web application for monitoring AI API quotas and rate-limit windows across multiple providers in one dark-themed dashboard. It polls external provider APIs, accepts webhook pushes from a local Antigravity Language Server sync script, stores historical usage snapshots in PostgreSQL, displays interactive 7-day charts, and sends automated push alerts via ntfy when usage thresholds are reached.
Architecture
+-----------------------------------+ POST /api/webhook/antigravity
| Windows Host (Antigravity IDE) | -------------------------------------+
| Push-AntigravityQuota.ps1 | |
| -> tokenwatch-sync.js | v
+-----------------------------------+ +------------------------------+
| TokenWatch Server (Express) |
+-----------------------------------+ REST API (30 min | Port 3000 |
| External APIs | cron + live fetch) | - Static UI (public/) |
| - POE (current_balance) | <-------------------> | - /api/quotas |
| - MiniMax (coding_plan/remains) | | - /api/history |
+-----------------------------------+ +--------------+---------------+
|
+----------------------------+----------------------------+
v v
+------------------------------+ +------------------------------+
| PostgreSQL Database | | ntfy Server |
| - quotas (history) | | Alert threshold notifications|
| - antigravity_latest (JSONB) | +------------------------------+
+------------------------------+
Features
- Multi-Provider Quota Tracking:
- POE: Tracks remaining point balance against a
2,500,000cap, daily refresh (75,000), expiring points, days until cap, points used today (calculated against the first UTC snapshot of the day), and a live UTC midnight refresh countdown. - MiniMax: Tracks
MiniMax (5h)andMiniMax (Weekly)usage percentages (model_name === 'general') with live reset countdowns. - Antigravity (AG): Tracks 5 separate quota buckets via webhook push (
AG Gemini (5h),AG Gemini (Weekly),AG Claude (5h),AG Claude (Weekly),AG Gemini 4 Argon (Weekly)), including individual reset timestamps (Heute,Morgen, or weekday + countdown).
- POE: Tracks remaining point balance against a
- Persistent Antigravity State: Incoming Antigravity webhook payloads are saved into the
antigravity_latestPostgreSQL table (JSONB) and automatically restored on server startup. - Automated Cron Snapshots & ntfy Alerts: Every 30 minutes (
*/30 * * * *),node-cronfetches all quotas, records them in PostgreSQL, and sends anntfynotification (Title: TokenWatch Alert,Tags: warning,robot) when the configured threshold (ALERT_THRESHOLD_PERCENT, default80) is crossed. - 7-Day History Chart: Interactive Chart.js line chart grouping snapshots into 5-minute intervals for
AG Gemini (5h),AG Claude (5h),POE, andMiniMax (5h). - 6 Selectable Progress Bar Themes: Switch live between
Standard,Pac-Man,Battery,Nyan Cat,Matrix, andLavathemes (also dynamically updates Chart.js dataset colors). - Confetti Milestone: Triggers a
canvas-confetticelebration and displaysLIMIT REACHED!(for non-POE providers) when a quota reaches100%. - Windows Antigravity Sync & Debug Tools: Includes
tokenwatch-sync.js,Push-AntigravityQuota.ps1(Task Scheduler-ready), and cross-platformfetch-quota.jsfor inspecting raw local Language Server quota responses.
How It Works & Tech Stack
Internal Workflow
- Server Startup (
src/server.ts): Initializes Express on0.0.0.0:3000, serves static assets frompublic/, initializes the PostgreSQL tables (quotasandantigravity_latest) viainitDb(), and restores cached Antigravity quotas viainitAntigravityFromDb(). - Quota Polling (
src/services/providers.ts):fetchPoeQuota()querieshttps://api.poe.com/usage/current_balance.fetchMinimaxQuota()querieshttps://api.minimax.io/v1/api/openplatform/coding_plan/remains.fetchAntigravityQuota()reads the in-memoryantigravityCachepopulated byPOST /api/webhook/antigravityor restored from PostgreSQL.
- Alerting Logic (
src/cron.ts&src/services/ntfy.ts):- For POE (where
percentagerepresents remaining quota), an alert is triggered whenpercentage <= (100 - ALERT_THRESHOLD_PERCENT)(default<= 20%remaining). - For MiniMax and Antigravity (where
percentagerepresents used quota), an alert is triggered whenpercentage >= ALERT_THRESHOLD_PERCENT(default>= 80%used).
- For POE (where
- Local Antigravity Sync (
tokenwatch-sync.js): Discovers runninglanguage_server*processes via PowerShell (Get-CimInstance Win32_Process), extracts--csrf_tokenand--extension_server_port, scans localhost listening ports (Get-NetTCPConnectionwithnetstat -anofallback), callsPOST /exa.language_server_pb.LanguageServerService/RetrieveUserQuotaSummary, and forwards the parsed buckets to/api/webhook/antigravity.
Tech Stack & Ports
| Component | Technology / Version | Details |
|---|---|---|
| Runtime | Node.js 24 (node:24-alpine) |
CommonJS TypeScript build (tsc -> dist/) |
| Backend | Express ^5.2.1, TypeScript ^7.0.2 |
REST API + static file server |
| Scheduler | node-cron ^4.6.0 |
Runs every 30 minutes (*/30 * * * *) |
| HTTP Client | axios ^1.20.0 |
Provider API calls & ntfy alerts |
| Database | PostgreSQL (postgres:15-alpine, pg ^8.23.0) |
Tables: quotas, antigravity_latest |
| Frontend | Vanilla HTML/CSS/JS, Chart.js, canvas-confetti |
Served from public/ |
| Default Port | 3000 (Container) / 3500 (Jannik-Cloud host bind) |
Configurable via PORT |
Prerequisites & Installation
Prerequisites
- Local Development: Node.js (v20+ / v24 recommended), npm, and a running PostgreSQL instance.
- Docker Deployment: Docker and Docker Compose.
- Antigravity Local Sync (Optional): Windows host with Antigravity IDE running, Node.js, and PowerShell.
Local Installation
-
Clone the repository:
git clone https://git.orfel.de/Jannik/TokenWatch.git cd TokenWatch -
Install dependencies:
npm install -
Create your environment file from
.env.example:cp .env.example .envEdit
.envwith your PostgreSQL credentials,NTFY_URL, and API keys. -
Run in development mode (using
tsx) or build for production:# Development npm run dev # Production build & start npm run build npm start
Docker Compose Setup
Start TokenWatch together with PostgreSQL (postgres:15-alpine):
cp .env.example .env
# Edit .env with your credentials and API keys
docker compose up -d
The dashboard will be available at http://localhost:3000.
Jannik-Cloud Production Deployment
A ready-to-use deployment template is provided in deployment-template/:
- Copy the contents of
deployment-template/intoservices/tokenwatch/in yourJannik-Cloudrepository. - Run
bash generate-env.shinsideservices/tokenwatch/to generate random PostgreSQL credentials and optionally encrypt.envto.env.age(usingkeys/age-public-key.txt). - Add your provider API keys (
POE_API_KEY,MINIMAX_API_KEY, etc.) as needed. - The included
tokenwatch.caddyconfigures reverse proxying fortw.orfel.de,token.orfel.de, andtokenwatch.orfel.detotokenwatch:3000, whiledocker-compose.ymlbinds127.0.0.1:3500:3000on the externaljannik-cloud-netnetwork. - Note:
.github/workflows/docker.ymlalso defines a GitHub Actions workflow that builds and pushesghcr.io/<owner>/<repo>:lateston pushes tomainormaster.
Configuration
Environment Variables (.env.example)
| Variable | Description | Default / Example |
|---|---|---|
PORT |
HTTP server port | 3000 |
DB_USER |
PostgreSQL username | postgres |
DB_HOST |
PostgreSQL hostname | postgres |
DB_NAME |
PostgreSQL database name | tokenwatch |
DB_PASSWORD |
PostgreSQL password | your_db_password |
DB_PORT |
PostgreSQL port | 5432 |
NTFY_URL |
ntfy topic URL for threshold alerts | https://ntfy.orfel.de/Token-Watch (fallback in ntfy.ts: https://ntfy.orfel.de/tokenwatch_dummy) |
ALERT_THRESHOLD_PERCENT |
Alert threshold percentage (>= used, or <= 100 - N remaining for POE) |
80 |
POE_API_KEY |
Bearer token for api.poe.com/usage/current_balance |
— |
MINIMAX_API_KEY |
Bearer token for api.minimax.io/v1/api/openplatform/coding_plan/remains |
— |
ANTIGRAVITY_API_KEY |
Optional Antigravity key placeholder in .env.example / Compose |
— |
ANTIGRAVITY_ENDPOINT |
Optional Antigravity endpoint placeholder in .env.example / Compose |
https://api.antigravity.google/v1/quota |
Docker Volumes
pgdata:/var/lib/postgresql/data— Persists PostgreSQLquotashistory andantigravity_lateststate indocker-compose.yml.
Usage
Web Dashboard
Open http://localhost:3000 (or your configured reverse-proxy domain) to:
- View real-time quota progress bars, reset times (
Heute/Morgen/weekday), and countdowns for POE, Antigravity, and MiniMax. - Switch the Progress Bar Style dropdown between:
StandardPac-ManBatteryNyan CatMatrixLava
- Inspect the 7-day usage trend in the History Chart.js graph.
API Endpoints
| Method | Endpoint | Description |
|---|---|---|
GET |
/api/quotas |
Returns current quota objects for all providers, enriched with meta.todayUsed for POE. |
GET |
/api/history |
Returns the last 7 days of rows from the quotas PostgreSQL table ordered chronologically. |
POST |
/api/webhook/antigravity |
Updates the 5 Antigravity quota entries and persists them to antigravity_latest. |
Example webhook payload accepted by POST /api/webhook/antigravity:
{
"gemini_5h_remaining": 85,
"gemini_weekly_remaining": 90,
"claude_5h_remaining": 100,
"claude_weekly_remaining": 75,
"gemini_argon_weekly_remaining": 100,
"gemini_5h_reset": "2026-01-01T15:00:00Z",
"gemini_weekly_reset": "2026-01-07T00:00:00Z",
"claude_5h_reset": null,
"claude_weekly_reset": null,
"gemini_argon_weekly_reset": null
}
Antigravity Local Sync (Windows)
- Verify
urlintokenwatch-sync.jspoints to your TokenWatch instance (default:https://tokenwatch.orfel.de/api/webhook/antigravity). - Run manually:
Or directly:
.\Push-AntigravityQuota.ps1node tokenwatch-sync.js - Windows Task Scheduler Automation:
- Trigger: Every 30 minutes
- Action: Start a program
- Program:
powershell - Arguments:
-ExecutionPolicy Bypass -File "C:\GitHub\TokenWatch\Push-AntigravityQuota.ps1"
- Debugging Raw Language Server Quotas:
Queries
node fetch-quota.js/exa.language_server_pb.LanguageServerService/GetUserStatuson the local Language Server (supports Windows, macOS, and Linux) and prints the complete JSON response.
Project Structure
TokenWatch/
├── .github/
│ └── workflows/
│ └── docker.yml # GitHub Actions Docker build & push to ghcr.io
├── deployment-template/
│ ├── README.md # Jannik-Cloud deployment guide
│ ├── docker-compose.yml # Production Compose using jannik-cloud-net
│ ├── generate-env.sh # Generates DB credentials & optional age encryption
│ ├── service.enabled # Jannik-Cloud service activation marker
│ └── tokenwatch.caddy # Caddy reverse proxy config
├── public/
│ ├── logos/ # Provider .ico assets
│ ├── app.js # Frontend fetching, countdowns, Chart.js & theme switcher
│ ├── favicon.png # TokenWatch logo & favicon
│ ├── index.html # Dashboard HTML
│ ├── logo-*.png / .ico / .svg # Provider icons (POE, Gemini, Claude, MiniMax, AG)
│ └── style.css # Dark UI & 6 progress bar theme styles
├── src/
│ ├── services/
│ │ ├── db.ts # PostgreSQL pool, schema init, history & AG persistence
│ │ ├── ntfy.ts # ntfy alert sender
│ │ └── providers.ts # POE, MiniMax & Antigravity quota handlers
│ ├── cron.ts # 30-minute quota logger & threshold alert job
│ └── server.ts # Express app & REST API endpoints
├── .env.example # Example environment configuration
├── Dockerfile # Node 24 Alpine TypeScript build container
├── docker-compose.yml # Local/standalone Compose with PostgreSQL 15
├── fetch-quota.js # Cross-platform Language Server quota debug script
├── language-server-process-utils.js# Process discovery & CLI arg extraction helpers
├── package.json # Dependencies and npm scripts
├── Push-AntigravityQuota.ps1 # Windows Task Scheduler wrapper script
├── tokenwatch-sync.js # Local Antigravity Language Server -> webhook sync
└── tsconfig.json # TypeScript compiler configuration
License
This project's own code and configuration are dedicated to the public domain under CC0 1.0 Universal — see LICENSE.
External dependencies installed via package managers or Docker images retain their respective open-source licenses.