tokenarchive

Tägliche Schnappschüsse deiner KI-Codierungsnutzung, für immer aufbewahrt.

ccusage kann dir sagen, was Claude Code, Codex, Gemini und Co. dich kosten – aber nur so weit zurück, wie die Logs auf deinem Rechner reichen, und diese Logs rotieren. tokenarchive erstellt einmal täglich einen Schnappschuss des ccusage-Berichts, bewahrt jeden Schnappschuss als append-only JSON-Archiv auf und rendert daraus ein Dashboard. Optional hält ein Cloudflare Worker eine Kopie des Archivs außerhalb deines Rechners, hinter einem Passkey.

Zwei Prinzipien prägen alles hier:

• Nichts wird jemals gelöscht. Schnappschüsse sind das Archiv; jede Datenbank ist eine abgeleitete Kopie, die daraus neu aufgebaut werden kann.

• Abwesenheit wird nie als Null gemeldet. Ein Tag ohne Schnappschuss sagt das aus. $0.00 würde behaupten, wir hätten nachgesehen und du hättest nichts ausgegeben.

Schnellstart (macOS)

npx tokenarchive

Der Installer fragt nach einem Gerätenamen und einer optionalen Worker-URL, legt die Laufzeit unter ~/.local/share/tokenarchive/app ab, plant den täglichen Job (23:50 plus bei jedem Login – das Skript ist idempotent), lässt security nach dem Ingest-Token fragen, sodass es nie durch die Hände des Installers geht, und beweist das Ganze mit einem echten Lauf. Du kannst es jederzeit erneut ausführen, um neu zu konfigurieren; --uninstall entfernt alles außer deinem Archiv.

Schnappschüsse landen in ~/.local/share/tokenarchive/{device}/{date}.json. Um es einmal auszuprobieren, ohne etwas zu installieren:

git clone https://github.com/ddyy/tokenarchive && cd tokenarchive && ./snapshot.sh

Andere Plattformen: Alles außer dem Planungs-Klebstoff ist portabel. sync.js, der Importer und das Dashboard sind reines Node; portiere snapshot.sh auf einen systemd-Timer oder Cron-Job und der Rest folgt.

Related MCP server: Semantic Code Search MCP Server

Das Dashboard

generate-dashboard.js erstellt eine einzelne eigenständige HTML-Datei – kein Framework, kein Server, keine externen Anfragen. Es importiert zuerst neue Schnappschüsse in ein lokales SQLite-Lesemodell (import-snapshots.js), sodass die Regenerierung inkrementell ist.

Jedes Panel ist ein Filter: Klicke oder ziehe über Modelle, Geräte, Agenten, Tage oder Abrechnungsfenster und der Rest der Seite folgt (⌘ fügt zur Auswahl hinzu, ⇧ erweitert sie). Filter kombinieren sich über Dimensionen mit UND und leben im URL-Fragment, sodass eine Ansicht mit einem Lesezeichen versehen werden kann.

Ein Anzeigen als-Schalter – über den Summen und erneut in der klebrigen Leiste, sobald sie wegscrollen – misst die gesamte Seite in Dollar oder in Tokens: das Diagramm und seine Achse, die Abdeckungsschattierung, die Abrechnungsfenster und jede Liste, die sich entsprechend neu sortiert. Wenn du über eine Zeile fährst, erhältst du den vollständigen Namen, der abgeschnitten werden musste, seine Kosten, Tokens, den implizierten Preis pro Million, seinen Anteil an dem, was auf dem Bildschirm ist, und – für Projekte – die Sitzungsanzahl und den Zeitraum, den sie abdecken:

Der Abdeckungsstreifen zeigt eine Zelle pro Kalendertag, sodass eine Lücke als Lücke sichtbar ist – Tage ohne Schnappschuss werden nie als Tage mit null Nutzung dargestellt:

Mehrere Geräte

Das Archiv ist von der Dateisystemebene an nach Gerät partitioniert: Schnappschüsse liegen in {data}/{device}/{date}.json, jede Datenbankzeile trägt das Gerät, und der Import ist nur Upsert. Maschinen verschmelzen oder überschreiben sich daher nie gegenseitig, und alles, was die Dateien beider Maschinen unter einem Datenverzeichnis ablegt, ergibt ein kombiniertes Archiv – ein Worker, ein synchronisierter Ordner oder ein kopiertes Verzeichnis funktionieren alle auf die gleiche Weise.

Die Gesundheit wird pro Gerät beurteilt: Jedes erhält seinen eigenen grünen/gelben/roten Punkt, sein eigenes Datum des letzten Schnappschusses und seine eigene Liste fehlender Tage, sodass eine aktuelle Maschine eine andere, die still geworden ist, nicht verbergen kann. Ein Gerät, das keine Meldungen mehr macht, behält seine gesamte Historie – das Archiv löscht nie; es zeigt nur die Lücke.

Der Worker unten ist der Weg, dies zu tun, ohne Dateien von Hand zu verschieben.

Der Worker (optional, empfohlen)

Das Verzeichnis worker/ ist ein Cloudflare Worker, der Schnappschuss-Pushes akzeptiert und dasselbe Dashboard von D1 aus bedient, hinter WebAuthn-Passkeys. Die rohen Schnappschüsse werden wörtlich in R2 aufbewahrt – das macht es zu einem Backup und nicht nur zu einer Ansicht: /admin/replay kann D1 aus dem Bucket neu aufbauen, ohne deinen Laptop. Siehe worker/README.md für das Fünf-Befehle-Deployment.

Nach dem Deployment registriere einen Passkey unter /auth/ – der erste Passkey beansprucht das Archiv; das Hinzufügen eines Passkeys eines anderen Geräts erfordert eine Anmeldung. Generiere dann ein gerätespezifisches Ingest-Token unter /admin (die Token-Anzeige enthält Einrichtungsanweisungen) und der tägliche Schnappschuss-Job pusht automatisch. Eine Maschine, die nie synchronisiert, hat nichts verloren: Die Dateien auf der Festplatte sind das Archiv, und die nächste erfolgreiche Synchronisierung holt auf. Veraltete Pushes können neuere Daten nicht überschreiben – der Ingest behält den neuesten Schnappschuss.

/admin verwaltet den Rest: Ingest-Tokens und schreibgeschützte MCP-Tokens (einmalig angezeigt, pro Gerät widerrufbar), Sitzungsschlüssel-Rotation, ein Schnappschuss-Inventar und /admin/replay, das D1 aus den R2-Originalen neu aufbaut.

Um eine zweite Maschine hinzuzufügen, führe den Installer dort mit derselben Worker-URL aus und präge ihr ein eigenes Ingest-Token – ein Token ingesst nur als das Gerät, für das es geprägt wurde, sodass eine Maschine nicht als eine andere schreiben kann und das Widerrufen eines Tokens die anderen nie berührt.

MCP

Frage deinen Agenten nach deiner eigenen Nutzung. Zwei Server, dieselben vier schreibgeschützten Tools (usage_summary, usage_by_project, usage_by_day, archive_health), eine gemeinsame Implementierung:

• Lokal, über das SQLite-Archiv auf dieser Maschine:

  claude mcp add tokenarchive node /path/to/tokenarchive/mcp-server.js

• Remote, vom Worker unter /mcp für Maschinen, die das Archiv nicht besitzen. Präge ein mcp-Token unter /admin, dann:

  claude mcp add --transport http tokenarchive https://YOUR-WORKER/mcp \
    --header "Authorization: Bearer YOUR-TOKEN"

Von Natur aus schreibgeschützt: Es gibt kein Tool, das etwas schreibt, löscht oder neu schreibt.

Konfiguration

Alles ist durch Umgebungsvariablen überschreibbar, nichts erfordert sie:

Tests

bash test/run.sh

Die meisten Suiten sind hermetisch. Drei (static, interaction, tooltip) laufen gegen das Dashboard, das du zuletzt unter ~/.local/share/tokenarchive/index.html generiert hast, benötigen also ein echtes Archiv auf der Maschine – führe zuerst einmal den Schnappschuss aus.

Lizenz

MIT