Tokenomy is a local Pi extension. It does not intentionally collect, transmit, or store API keys.

Tokenomy may create .pi/tokenomy-stats.json and .pi/tokenomy-cache/ in projects where it runs. The stats file stores local routing counters and a deprecated pre-v2 savings field:

• legacy lifetime model-rank savings proxy
• routed prompt count
• Tokenomy session count
• classifier cache hit count
• project digest use count
• memory injection count
• adaptive fallback count
• compression guard rejection count
• per-intent route counters
• last update timestamp

The classifier cache stores routing decisions keyed by a normalized prompt hash, context bucket, intent, and risk. The project digest stores compact routing metadata such as intent counts and the last selected tier/model.

Routing telemetry, when enabled, stores recent decision metadata in .pi/tokenomy-cache/routing-history.json. It includes prompt hashes, prompt size, context bucket, selected tier/source/model, confidence, signals, usage status, provider-reported token/cost totals, and estimated plan credits. For live classifier calls, it also includes classifier usage and compression guard status/counts, but not the protected signal-line text. It does not store raw prompt text or model responses. It can also store language/mode labels, experiment cohorts, user feedback, correction flags, evaluator scores, and aggregate tool-result sizes. It never stores raw tool arguments or results.

Telemetry rollups are stored in .pi/tokenomy-cache/telemetry-rollups.json. They aggregate daily, monthly, and lifetime counters such as input/cached/output tokens, optional reasoning, request counts, cost, plan-credit estimates, measured/unavailable coverage, route distribution, classifier overhead, adaptive fallbacks, prompt shape, completion stop-reason categories, tool call/error counts, retry runs, compactions, verified-feedback counts, evaluator score totals, tool-output sizes, duplicate-call counts, truncation counts, and removed-token counts, plus measured compaction token deltas. Rollups do not store raw prompt text, prompt hashes, tool arguments/results, model responses, API keys, or auth headers.

When the provider exposes recognized rate-limit or usage response headers, Tokenomy stores the latest sanitized subset in .pi/tokenomy-cache/account-limits.json. The allowlist excludes authorization, cookies, and unrelated headers; values containing line breaks are rejected and stored values are length-limited. This snapshot is provider/process scoped, not an account-wide ledger.

Tokenomy does not store raw prompt text, model responses, API keys, or auth headers during normal operation.

External rate cards and account-quota snapshots must use project-relative paths. Tokenomy rejects absolute paths and paths that escape the project root. Account quota files are supplied by the user or a companion/Enterprise adapter; they should contain counters only, never cookies, OAuth tokens, or API keys. An explicitly configured registry.rateCardUrl performs an HTTPS GET during session startup only when the current card is stale by refreshHours. The response is size-limited and schema-validated before it replaces the local rate-card file.

If debug.trace is explicitly enabled, Tokenomy writes a local JSONL debug trace under .pi/tokenomy-cache/debug/session-*.jsonl. Payload fields are redacted by default. Setting debug.redact to false may record raw prompts, model/tool outputs, classifier prompts/responses, memory context, compression data, routing decisions, and internal errors. Trace files use mode 0600 and cache directories use 0700 where POSIX permissions are supported. Old traces expire after debug.retentionDays; /tokenomy debug purge removes them now.

JSON state files use a per-file lock and atomic rename so a crash cannot leave a partially written document. Stale locks are recovered. Statistics, routing history, and telemetry rollups perform their full read-modify-write transaction under that lock, so concurrent Pi processes preserve independent increments and entries. Replaceable caches, memory, and digest snapshots remain atomic last-completed writes.

/tokenomy data inventories project-local state. Selective purge commands remove cache, telemetry, memory, or debug data without configuration; purging all data requires confirmation when UI is available.

Prompt-shape analysis uses the local compromise NLP library. It does not send prompt text to an external service.

Project memory, when enabled, stores short durable facts in .pi/tokenomy-cache/project-memory.json. Examples include package name, npm script commands, known implementation file paths, and CI/release workflow hints. Tokenomy does not store raw prompts or model responses in project memory. Memory injection is advisory and explicitly lower priority than the current user prompt.

The local heuristic uses no model tokens. If the classifier is enabled, Tokenomy may send an ambiguous prompt excerpt to the configured classifier model through Pi's authenticated provider.

If quality.evaluatorEnabled is explicitly enabled, Tokenomy sends a bounded copy of the current task and assistant output to the configured evaluator model. This does not persist the raw content in normal telemetry, but it is an additional authenticated model call and consumes quota.

For large prompts, Tokenomy can simplify the classifier excerpt locally before the classifier call. This reduces prompt size but may still include relevant error lines, file paths, and counts from the user's prompt.

TokenShrink prompt compression runs locally through the tokenshrink SDK and does not call external APIs. It is applied only to classifier excerpts, not to the original agent prompt. It is enabled by default and can be disabled with promptSimplification.compressionEnabled: false.

Set this to disable classifier calls:

{
  "classifier": {
    "enabled": false
  }
}

Tool management is disabled by default:

{
  "tools": {
    "manage": false
  }
}

If enabled, Tokenomy can change Pi's active tools for a prompt. Review the configured readOnlyTools and writeTools before enabling this in shared or sensitive projects.

For now, report security issues privately to the repository owner before public disclosure. Include:

• Tokenomy version or commit
• Pi version
• affected config
• reproduction steps
• whether prompt text, files, or credentials may have been exposed