15 KiB
TokenWatch
Selbstgehosteter API-Quota- & Limit-Tracker mit Live-Dashboard, 7-Tage-Verlaufsdiagramm und ntfy-Benachrichtigungen.
Überblick
TokenWatch ist eine selbstgehostete Webanwendung zur zentralen Überwachung von KI-API-Kontingenten und Rate-Limit-Fenstern über mehrere Anbieter hinweg. Die Anwendung fragt externe Provider-APIs ab, empfängt Webhook-Updates eines lokalen Antigravity-Language-Server-Sync-Skripts, speichert Verlaufsdaten in PostgreSQL, stellt interaktive 7-Tage-Verläufe grafisch dar und verschickt automatische Push-Warnungen über ntfy, sobald konfigurierte Schwellenwerte überschritten werden.
Architektur
+-----------------------------------+ POST /api/webhook/antigravity
| Windows-Host (Antigravity IDE) | -------------------------------------+
| Push-AntigravityQuota.ps1 | |
| -> tokenwatch-sync.js | v
+-----------------------------------+ +------------------------------+
| TokenWatch-Server (Express) |
+-----------------------------------+ REST-API (30-Min- | Port 3000 |
| Externe APIs | Cron + Live-Abruf) | - Statische UI (public/) |
| - POE (current_balance) | <-------------------> | - /api/quotas |
| - MiniMax (coding_plan/remains) | | - /api/history |
+-----------------------------------+ +--------------+---------------+
|
+----------------------------+----------------------------+
v v
+------------------------------+ +------------------------------+
| PostgreSQL-Datenbank | | ntfy-Server |
| - quotas (Verlauf) | | Schwellenwert-Warnungen |
| - antigravity_latest (JSONB) | +------------------------------+
+------------------------------+
Funktionen
- Multi-Provider-Quota-Tracking:
- POE: Überwacht den aktuellen Punktestand im Verhältnis zum Limit von
2.500.000, täglichem Refresh (75.000), verfallenden Punkten, Tagen bis zum Cap, dem heutigen Tagesverbrauch (berechnet gegen den ersten UTC-Snapshot des Tages) sowie einem Live-Countdown bis 00:00 Uhr UTC. - MiniMax: Überwacht
MiniMax (5h)undMiniMax (Weekly)in Prozent (model_name === 'general') inklusive Live-Reset-Countdowns. - Antigravity (AG): Überwacht 5 separate Kontingente per Webhook-Push (
AG Gemini (5h),AG Gemini (Weekly),AG Claude (5h),AG Claude (Weekly),AG Gemini 4 Argon (Weekly)) inklusive individueller Reset-Zeitstempel (Heute,Morgenoder Wochentag + Countdown).
- POE: Überwacht den aktuellen Punktestand im Verhältnis zum Limit von
- Persistenter Antigravity-Status: Eingehende Webhook-Daten werden in der PostgreSQL-Tabelle
antigravity_latest(JSONB) gespeichert und beim Serverstart automatisch wiederhergestellt. - Automatisierte Cron-Snapshots & ntfy-Alerts: Alle 30 Minuten (
*/30 * * * *) ruftnode-cronalle Quotas ab, speichert sie in PostgreSQL und sendet bei Überschreitung vonALERT_THRESHOLD_PERCENT(Standard:80) einentfy-Meldung (Title: TokenWatch Alert,Tags: warning,robot). - 7-Tage-Verlaufsdiagramm: Interaktives Chart.js-Liniendiagramm, das Datenpunkte in 5-Minuten-Intervallen für
AG Gemini (5h),AG Claude (5h),POEundMiniMax (5h)gruppiert. - 6 wählbare Fortschrittsbalken-Themes: Live-Wechsel zwischen
Standard,Pac-Man,Battery,Nyan Cat,MatrixundLava(passt auch die Chart.js-Farben dynamisch an). - Konfetti-Effekt bei 100 %: Löst bei Erreichen von
100 %einecanvas-confetti-Animation aus und zeigt bei Nicht-POE-ProvidernLIMIT REACHED!an. - Lokale Antigravity-Sync- & Debug-Werkzeuge: Enthält
tokenwatch-sync.js,Push-AntigravityQuota.ps1(für die Windows-Aufgabenplanung) sowie das plattformübergreifende Debug-Skriptfetch-quota.jszum Auslesen der Rohantwort des lokalen Language Servers.
Funktionsweise & Tech-Stack
Interner Ablauf
- Serverstart (
src/server.ts): Startet Express auf0.0.0.0:3000, liefert statische Dateien auspublic/aus, initialisiert die PostgreSQL-Tabellen (quotasundantigravity_latest) überinitDb()und lädt gespeicherte Antigravity-Werte überinitAntigravityFromDb(). - Quota-Abruf (
src/services/providers.ts):fetchPoeQuota()fragthttps://api.poe.com/usage/current_balanceab.fetchMinimaxQuota()fragthttps://api.minimax.io/v1/api/openplatform/coding_plan/remainsab.fetchAntigravityQuota()liest den In-Memory-antigravityCache, der überPOST /api/webhook/antigravityaktualisiert oder beim Start aus PostgreSQL geladen wird.
- Alert-Logik (
src/cron.ts&src/services/ntfy.ts):- Bei POE (hier steht
percentagefür das verbleibende Kontingent) wird gewarnt, wennpercentage <= (100 - ALERT_THRESHOLD_PERCENT)(Standard:<= 20 %verbleibend). - Bei MiniMax und Antigravity (hier steht
percentagefür das verbrauchte Kontingent) wird gewarnt, wennpercentage >= ALERT_THRESHOLD_PERCENT(Standard:>= 80 %verbraucht).
- Bei POE (hier steht
- Lokaler Antigravity-Sync (
tokenwatch-sync.js): Sucht laufendelanguage_server*-Prozesse über PowerShell (Get-CimInstance Win32_Process), liest--csrf_tokenund--extension_server_portaus, ermittelt offene Loopback-Ports (Get-NetTCPConnectionmitnetstat -anoals Fallback), ruftPOST /exa.language_server_pb.LanguageServerService/RetrieveUserQuotaSummaryauf und sendet die extrahierten Werte an/api/webhook/antigravity.
Tech-Stack & Ports
| Komponente | Technologie / Version | Details |
|---|---|---|
| Laufzeitumgebung | Node.js 24 (node:24-alpine) |
CommonJS-TypeScript-Build (tsc -> dist/) |
| Backend | Express ^5.2.1, TypeScript ^7.0.2 |
REST-API + Auslieferung statischer Dateien |
| Scheduler | node-cron ^4.6.0 |
Läuft alle 30 Minuten (*/30 * * * *) |
| HTTP-Client | axios ^1.20.0 |
Provider-API-Abfragen & ntfy-Alerts |
| Datenbank | PostgreSQL (postgres:15-alpine, pg ^8.23.0) |
Tabellen: quotas, antigravity_latest |
| Frontend | Natives HTML/CSS/JS, Chart.js, canvas-confetti |
Ausgeliefert aus public/ |
| Standard-Port | 3000 (Container) / 3500 (Jannik-Cloud-Host-Bind) |
Konfigurierbar über PORT |
Voraussetzungen & Installation
Voraussetzungen
- Lokale Entwicklung: Node.js (v20+ / v24 empfohlen), npm und eine laufende PostgreSQL-Instanz.
- Docker-Deployment: Docker und Docker Compose.
- Antigravity-Sync (optional): Windows-Rechner mit laufender Antigravity IDE, Node.js und PowerShell.
Lokale Installation
-
Repository klonen:
git clone https://git.orfel.de/Jannik/TokenWatch.git cd TokenWatch -
Abhängigkeiten installieren:
npm install -
Umgebungsdatei aus
.env.exampleerstellen:cp .env.example .envDanach PostgreSQL-Zugangsdaten,
NTFY_URLund API-Keys in.enveintragen. -
Im Entwicklungsmodus (
tsx) starten oder für Produktion bauen:# Entwicklung npm run dev # Produktions-Build & Start npm run build npm start
Docker-Compose-Setup
TokenWatch gemeinsam mit PostgreSQL (postgres:15-alpine) starten:
cp .env.example .env
# .env mit Zugangsdaten und API-Keys ausfüllen
docker compose up -d
Das Dashboard ist anschließend unter http://localhost:3000 erreichbar.
Jannik-Cloud-Produktivdeployment
Eine fertige Deployment-Vorlage liegt in deployment-template/:
- Den Inhalt von
deployment-template/in das Verzeichnisservices/tokenwatch/imJannik-Cloud-Repository kopieren. - In
services/tokenwatch/das Skriptbash generate-env.shausführen, um zufällige PostgreSQL-Zugangsdaten zu generieren und optional.envnach.env.agezu verschlüsseln (überkeys/age-public-key.txt). - Bei Bedarf Provider-API-Keys (
POE_API_KEY,MINIMAX_API_KEYusw.) ergänzen. tokenwatch.caddykonfiguriert den Reverse-Proxy fürtw.orfel.de,token.orfel.deundtokenwatch.orfel.deauftokenwatch:3000;docker-compose.ymlbindet127.0.0.1:3500:3000im externen Netzwerkjannik-cloud-net.- Hinweis:
.github/workflows/docker.ymlenthält zudem einen GitHub-Actions-Workflow, der bei Pushes aufmainodermasterein Image nachghcr.io/<owner>/<repo>:latestbaut und pusht.
Konfiguration
Umgebungsvariablen (.env.example)
| Variable | Beschreibung | Standard / Beispiel |
|---|---|---|
PORT |
HTTP-Server-Port | 3000 |
DB_USER |
PostgreSQL-Benutzername | postgres |
DB_HOST |
PostgreSQL-Hostname | postgres |
DB_NAME |
Name der PostgreSQL-Datenbank | tokenwatch |
DB_PASSWORD |
PostgreSQL-Passwort | your_db_password |
DB_PORT |
PostgreSQL-Port | 5432 |
NTFY_URL |
ntfy-Topic-URL für Schwellenwert-Alerts | https://ntfy.orfel.de/Token-Watch (Fallback in ntfy.ts: https://ntfy.orfel.de/tokenwatch_dummy) |
ALERT_THRESHOLD_PERCENT |
Schwellenwert in Prozent (>= verbraucht bzw. <= 100 - N verbleibend bei POE) |
80 |
POE_API_KEY |
Bearer-Token für api.poe.com/usage/current_balance |
— |
MINIMAX_API_KEY |
Bearer-Token für api.minimax.io/v1/api/openplatform/coding_plan/remains |
— |
ANTIGRAVITY_API_KEY |
Optionaler Platzhalter in .env.example / Compose |
— |
ANTIGRAVITY_ENDPOINT |
Optionaler Platzhalter in .env.example / Compose |
https://api.antigravity.google/v1/quota |
Docker-Volumes
pgdata:/var/lib/postgresql/data— Persistiert indocker-compose.ymlden Verlauf inquotassowie den Zustand inantigravity_latest.
Nutzung
Web-Dashboard
Öffne http://localhost:3000 (bzw. deine konfigurierte Domain), um:
- Aktuelle Fortschrittsbalken, Reset-Zeiten (
Heute/Morgen/Wochentag) und Countdowns für POE, Antigravity und MiniMax anzuzeigen. - Über das Dropdown Progress Bar Style zwischen 6 Designs zu wechseln:
StandardPac-ManBatteryNyan CatMatrixLava
- Den 7-Tage-Verlauf im Chart.js-Bereich History zu verfolgen.
API-Endpunkte
| Methode | Endpunkt | Beschreibung |
|---|---|---|
GET |
/api/quotas |
Liefert die aktuellen Quota-Objekte aller Provider inklusive meta.todayUsed für POE. |
GET |
/api/history |
Liefert die letzten 7 Tage aus der PostgreSQL-Tabelle quotas in chronologischer Reihenfolge. |
POST |
/api/webhook/antigravity |
Aktualisiert die 5 Antigravity-Einträge im Speicher und persistiert sie in antigravity_latest. |
Beispiel-Payload für 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
}
Lokaler Antigravity-Sync (Windows)
- Stelle sicher, dass
urlintokenwatch-sync.jsauf deine TokenWatch-Instanz zeigt (Standard:https://tokenwatch.orfel.de/api/webhook/antigravity). - Manuell ausführen:
Oder direkt per Node:
.\Push-AntigravityQuota.ps1node tokenwatch-sync.js - Automatisierung über Windows-Aufgabenplanung:
- Trigger: Alle 30 Minuten
- Aktion: Programm starten
- Programm:
powershell - Argumente:
-ExecutionPolicy Bypass -File "C:\GitHub\TokenWatch\Push-AntigravityQuota.ps1"
- Rohdaten des Language Servers debuggen:
Fragt
node fetch-quota.js/exa.language_server_pb.LanguageServerService/GetUserStatusbeim lokalen Language Server ab (unterstützt Windows, macOS und Linux) und gibt die vollständige JSON-Antwort aus.
Projektstruktur
TokenWatch/
├── .github/
│ └── workflows/
│ └── docker.yml # GitHub-Actions-Workflow zum Bauen/Pushen nach ghcr.io
├── deployment-template/
│ ├── README.md # Deployment-Anleitung für Jannik-Cloud
│ ├── docker-compose.yml # Produktives Compose mit jannik-cloud-net
│ ├── generate-env.sh # Erzeugt DB-Passwörter & optional .env.age
│ ├── service.enabled # Aktivierungsdatei für Jannik-Cloud
│ └── tokenwatch.caddy # Caddy-Reverse-Proxy-Konfiguration
├── public/
│ ├── logos/ # Provider-.ico-Dateien
│ ├── app.js # Frontend-Logik, Countdowns, Chart.js & Themes
│ ├── 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 Fortschrittsbalken-Themes
├── src/
│ ├── services/
│ │ ├── db.ts # PostgreSQL-Pool, Tabellen-Init, Verlauf & AG-Persistenz
│ │ ├── ntfy.ts # ntfy-Benachrichtigungen
│ │ └── providers.ts # POE-, MiniMax- & Antigravity-Provider-Logik
│ ├── cron.ts # 30-Minuten-Cron-Job & Schwellenwert-Prüfung
│ └── server.ts # Express-App & REST-API-Endpunkte
├── .env.example # Beispiel-Umgebungsvariablen
├── Dockerfile # Node-24-Alpine-Container mit TypeScript-Build
├── docker-compose.yml # Lokales/Standalone-Compose mit PostgreSQL 15
├── fetch-quota.js # Plattformübergreifendes Debug-Skript für Language Server
├── language-server-process-utils.js# Prozesssuche & CLI-Argument-Extraktion
├── package.json # Abhängigkeiten und npm-Skripte
├── Push-AntigravityQuota.ps1 # PowerShell-Wrapper für Windows-Aufgabenplanung
├── tokenwatch-sync.js # Lokaler Antigravity-Language-Server -> Webhook-Sync
└── tsconfig.json # TypeScript-Konfiguration
Lizenz
Der eigene Quellcode und die Konfiguration dieses Projekts stehen unter CC0 1.0 Universal (Public Domain) — Details in LICENSE.
Externe Abhängigkeiten, die über Paketmanager oder Docker-Images installiert werden, behalten ihre jeweiligen eigenen Open-Source-Lizenzen.