tokenarchive

Instantáneas diarias de tu uso de codificación con IA, conservadas para siempre.

ccusage puede decirte cuánto te cuestan Claude Code, Codex, Gemini y compañía, pero solo hasta donde llegan los registros en tu máquina, y esos registros rotan. tokenarchive toma una instantánea del informe de ccusage una vez al día, guarda cada instantánea como un archivo JSON de solo añadido, y genera un panel a partir de él. Opcionalmente, un Cloudflare Worker mantiene una copia del archivo fuera de tu máquina, detrás de una passkey.

Dos principios dan forma a todo esto:

• Nada se borra jamás. Las instantáneas son el archivo; cada base de datos es una copia derivada que se puede reconstruir a partir de ellas.

• La ausencia nunca se informa como cero. Un día sin instantánea lo dice. $0.00 afirmaría que miramos y no gastaste nada.

Inicio rápido (macOS)

npx tokenarchive

El instalador solicita un nombre de dispositivo y una URL de Worker opcional, coloca el runtime en ~/.local/share/tokenarchive/app, programa la tarea diaria (23:50 más cada inicio de sesión — el script es idempotente), permite que security solicite el token de ingesta para que nunca pase por las manos del instalador, y prueba todo con una ejecución real. Puedes volver a ejecutarlo en cualquier momento para reconfigurar; --uninstall elimina todo excepto tu archivo.

Las instantáneas se guardan en ~/.local/share/tokenarchive/{device}/{date}.json. Para probarlo una vez sin instalar nada:

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

Otras plataformas: todo excepto el pegamento de programación es portátil. sync.js, el importador y el panel son Node puro; porta snapshot.sh a un temporizador systemd o a un trabajo cron y el resto sigue.

Related MCP server: Semantic Code Search MCP Server

El panel

generate-dashboard.js genera un único archivo HTML autocontenido — sin framework, sin servidor, sin solicitudes externas. Primero importa nuevas instantáneas a un modelo de lectura SQLite local (import-snapshots.js), por lo que la regeneración es incremental.

Cada panel es un filtro: haz clic o arrastra sobre modelos, dispositivos, agentes, días o ventanas de facturación y el resto de la página lo sigue (⌘ añade a una selección, ⇧ la extiende). Los filtros se combinan entre dimensiones con AND, y viven en el fragmento de URL, por lo que una vista se puede marcar como favorito.

Un interruptor Mostrar como — sobre los totales, y de nuevo en la barra fija cuando se desplazan — mide toda la página en dólares o en tokens: el gráfico y su eje, el sombreado de cobertura, las ventanas de facturación y cada lista, que se reordena para coincidir. Al pasar el cursor sobre una fila se muestra el nombre completo que tuvo que truncar, su costo, tokens, la tasa implícita por millón, su participación en lo que está en pantalla y — para proyectos — el número de sesiones y el lapso que cubren:

La franja de cobertura muestra una celda por día calendario, por lo que un hueco se ve como un hueco — los días sin instantánea nunca se dibujan como días de uso cero:

Múltiples dispositivos

El archivo está particionado por dispositivo desde el sistema de archivos: las instantáneas viven en {data}/{device}/{date}.json, cada fila de la base de datos lleva el dispositivo, y la importación es solo de actualización/inserción. Por lo tanto, las máquinas nunca se fusionan ni se pisan entre sí, y cualquier cosa que coloque los archivos de ambas máquinas bajo un mismo directorio de datos te da un archivo combinado — un Worker, una carpeta sincronizada o un directorio copiado funcionan igual.

La salud se juzga por dispositivo: cada uno tiene su propio punto verde/ámbar/rojo, su propia fecha de última instantánea y su propia lista de días faltantes, por lo que una máquina actual no puede ocultar a otra que se ha quedado en silencio. Un dispositivo que deja de informar conserva todo su historial — el archivo nunca borra; solo muestra el hueco.

El Worker de abajo es la forma de hacer esto sin mover archivos a mano.

El Worker (opcional, recomendado)

El directorio worker/ es un Cloudflare Worker que acepta envíos de instantáneas y sirve el mismo panel desde D1, detrás de passkeys WebAuthn. Las instantáneas crudas se guardan textualmente en R2 — eso es lo que lo convierte en una copia de seguridad en lugar de una vista: /admin/replay puede reconstruir D1 desde el bucket sin tu portátil. Consulta worker/README.md para el despliegue de cinco comandos.

Una vez desplegado, registra una passkey en /auth/ — la primera passkey reclama el archivo; añadir la passkey de otro dispositivo requiere haber iniciado sesión. Luego genera un token de ingesta por dispositivo en /admin (la revelación del token incluye instrucciones de configuración) y el trabajo diario de instantáneas se envía automáticamente. Una máquina que nunca sincroniza no ha perdido nada: los archivos en disco son el archivo, y la próxima sincronización exitosa se pone al día. Los envíos obsoletos no pueden sobrescribir datos más nuevos — la ingesta conserva la instantánea más reciente.

/admin gestiona el resto: tokens de ingesta y tokens MCP de solo lectura (mostrados una vez, revocables por dispositivo), rotación de claves de sesión, un inventario de instantáneas y /admin/replay, que reconstruye D1 desde los originales de R2.

Para añadir una segunda máquina, ejecuta el instalador allí con la misma URL de Worker y acuña su propio token de ingesta — un token solo ingesta como el dispositivo para el que fue acuñado, por lo que una máquina no puede escribir como otra y revocar uno nunca afecta a los demás.

MCP

Pregunta a tu agente sobre tu propio uso. Dos servidores, las mismas cuatro herramientas de solo lectura (usage_summary, usage_by_project, usage_by_day, archive_health), una implementación compartida:

• Local, sobre el archivo SQLite en esta máquina:

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

• Remoto, servido por el Worker en /mcp para máquinas que no tienen el archivo. Acuña un token mcp en /admin, luego:

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

Solo lectura por construcción: no hay ninguna herramienta que escriba, borre o reescriba nada.

Configuración

Todo se puede sobrescribir con variables de entorno, nada lo requiere:

Pruebas

bash test/run.sh

La mayoría de las suites son herméticas. Tres (static, interaction, tooltip) se ejecutan contra el panel que generaste por última vez en ~/.local/share/tokenarchive/index.html, por lo que necesitan un archivo real en la máquina — ejecuta la instantánea una vez primero.

Licencia

MIT