Privacy and data
TokenInsights captures metadata from durable local harness artifacts. Raw evidence never stores prompt text, assistant text, tool arguments/output, request headers, secrets, raw provider payloads or full source paths.
Allowed metadata includes counters, timestamps, models, providers, session/native identifiers, hashed location keys and bounded display labels. Directory enrichment may retain a collector-local directory label (home-relative where possible); full source artifact paths and Git remote URLs stay out of raw evidence. Hashes and basenames can still identify a project; metadata is not anonymous.
Storage
Default directory: ${XDG_DATA_HOME:-~/.local/share}/tokeninsights/.
| File | Purpose | Flag / environment |
|---|---|---|
| collector.sqlite | Continuity, immutable evidence/outbox and checkpoints | --collector-db-path / TOKENINSIGHTS_COLLECTOR_DB_PATH |
| server.sqlite | Evidence, receipts, processing and published token history | --server-db-path / TOKENINSIGHTS_SERVER_DB_PATH |
SQLite is the sole backend. Roles cannot alias and wrong/incompatible contracts reject without mutation. Collector schema 20 and token schema 1 remain unchanged. There are no account/application/jobs stores. Former user files remain untouched; the redesign neither migrates nor deletes them. Keep stopped backups of both current stores and relevant SQLite companions.
Connections and secrets
Local viewers use a private Unix socket. SSH uses system SSH to reach the selected machine's backend; TCP uses an explicit temporary pinned TLS gateway. Connecting reads that backend's history, without uploading/merging local evidence.
remote prints a temporary credential-bearing connection command. Keep it private.
The native client verifies the public-key pin before submitting the credential;
every request authenticates. The credential grants reads, progress, leases and
default capture only. Stop invalidates it. Same-host use still uses TCP.
Browser dashboards bind loopback and receive redacted connection metadata, never the TCP secret. Native desktop handoff keeps secrets on a private rendezvous socket; OS URLs contain only an opaque ID. No credential files or saved pairing profiles are created. Remote connections explains access limits.
Accounting
Raw missing provider/model values stay absent/null. Canonical absence becomes
unknown; Claude Code records without explicit provider use maybe-anthropic
with inferred provenance. Pi openai-codex canonicalizes to openai;
fireworks-ai to fireworks, and Fireworks model prefixes
accounts/fireworks/models/ are removed.
Stable native identities, never equal counters or payload hashes alone, determine duplicate consumption. All five token components stay atomic. Confirmed usage and ambiguous estimates remain separate; missing sessions cannot become canonical rows. Retained sanitized evidence permits reprocessing, but cannot recover fields never captured. Capture runs on launch and explicit Refresh, with no periodic scanning.