Files
Jannik 665f12a369
Build and Push Docker Image / build-and-push (push) Canceled after 0s
chore(license): standardize on CC0-1.0 and third-party notices
2026-11-18 01:18:15 +01:00

15 KiB

TokenWatch Logo

TokenWatch

Self-hosted API quota & token limit tracker with live dashboard, 7-day history charts, and ntfy alerts.

🇬🇧 English · 🇩🇪 Deutsch


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,000 cap, 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) and MiniMax (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).
  • Persistent Antigravity State: Incoming Antigravity webhook payloads are saved into the antigravity_latest PostgreSQL table (JSONB) and automatically restored on server startup.
  • Automated Cron Snapshots & ntfy Alerts: Every 30 minutes (*/30 * * * *), node-cron fetches all quotas, records them in PostgreSQL, and sends an ntfy notification (Title: TokenWatch Alert, Tags: warning,robot) when the configured threshold (ALERT_THRESHOLD_PERCENT, default 80) 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, and MiniMax (5h).
  • 6 Selectable Progress Bar Themes: Switch live between Standard, Pac-Man, Battery, Nyan Cat, Matrix, and Lava themes (also dynamically updates Chart.js dataset colors).
  • Confetti Milestone: Triggers a canvas-confetti celebration and displays LIMIT REACHED! (for non-POE providers) when a quota reaches 100%.
  • Windows Antigravity Sync & Debug Tools: Includes tokenwatch-sync.js, Push-AntigravityQuota.ps1 (Task Scheduler-ready), and cross-platform fetch-quota.js for inspecting raw local Language Server quota responses.

How It Works & Tech Stack

Internal Workflow

  1. Server Startup (src/server.ts): Initializes Express on 0.0.0.0:3000, serves static assets from public/, initializes the PostgreSQL tables (quotas and antigravity_latest) via initDb(), and restores cached Antigravity quotas via initAntigravityFromDb().
  2. Quota Polling (src/services/providers.ts):
    • fetchPoeQuota() queries https://api.poe.com/usage/current_balance.
    • fetchMinimaxQuota() queries https://api.minimax.io/v1/api/openplatform/coding_plan/remains.
    • fetchAntigravityQuota() reads the in-memory antigravityCache populated by POST /api/webhook/antigravity or restored from PostgreSQL.
  3. Alerting Logic (src/cron.ts & src/services/ntfy.ts):
    • For POE (where percentage represents remaining quota), an alert is triggered when percentage <= (100 - ALERT_THRESHOLD_PERCENT) (default <= 20% remaining).
    • For MiniMax and Antigravity (where percentage represents used quota), an alert is triggered when percentage >= ALERT_THRESHOLD_PERCENT (default >= 80% used).
  4. Local Antigravity Sync (tokenwatch-sync.js): Discovers running language_server* processes via PowerShell (Get-CimInstance Win32_Process), extracts --csrf_token and --extension_server_port, scans localhost listening ports (Get-NetTCPConnection with netstat -ano fallback), calls POST /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

  1. Clone the repository:

    git clone https://git.orfel.de/Jannik/TokenWatch.git
    cd TokenWatch
    
  2. Install dependencies:

    npm install
    
  3. Create your environment file from .env.example:

    cp .env.example .env
    

    Edit .env with your PostgreSQL credentials, NTFY_URL, and API keys.

  4. 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/:

  1. Copy the contents of deployment-template/ into services/tokenwatch/ in your Jannik-Cloud repository.
  2. Run bash generate-env.sh inside services/tokenwatch/ to generate random PostgreSQL credentials and optionally encrypt .env to .env.age (using keys/age-public-key.txt).
  3. Add your provider API keys (POE_API_KEY, MINIMAX_API_KEY, etc.) as needed.
  4. The included tokenwatch.caddy configures reverse proxying for tw.orfel.de, token.orfel.de, and tokenwatch.orfel.de to tokenwatch:3000, while docker-compose.yml binds 127.0.0.1:3500:3000 on the external jannik-cloud-net network.
  5. Note: .github/workflows/docker.yml also defines a GitHub Actions workflow that builds and pushes ghcr.io/<owner>/<repo>:latest on pushes to main or master.

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 PostgreSQL quotas history and antigravity_latest state in docker-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:
    1. Standard
    2. Pac-Man
    3. Battery
    4. Nyan Cat
    5. Matrix
    6. Lava
  • 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)

  1. Verify url in tokenwatch-sync.js points to your TokenWatch instance (default: https://tokenwatch.orfel.de/api/webhook/antigravity).
  2. Run manually:
    .\Push-AntigravityQuota.ps1
    
    Or directly:
    node tokenwatch-sync.js
    
  3. Windows Task Scheduler Automation:
    • Trigger: Every 30 minutes
    • Action: Start a program
    • Program: powershell
    • Arguments: -ExecutionPolicy Bypass -File "C:\GitHub\TokenWatch\Push-AntigravityQuota.ps1"
  4. Debugging Raw Language Server Quotas:
    node fetch-quota.js
    
    Queries /exa.language_server_pb.LanguageServerService/GetUserStatus on 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.