pi-cost-tracker

Token & cost accounting for the pi coding agent.

pi shows you the last message's token counts. pi-cost-tracker answers the questions you actually have at the end of a session:

• What did this session cost me? — every LLM call attributed to the turn that triggered it, including tool-embedded LLM calls (nested usage) and compaction summaries, in separate buckets.
• Which turns were expensive? — per-turn cost/IO breakdown with the prompt that caused it.
• What did each model cost? — per-model breakdown for mixed-model sessions.
• How is my cache doing? — share of billed input served from prompt cache.
• What am I burning across sessions? — a JSONL ledger under ~/.pi/agent/ aggregates every session, queryable via /cost-history.

Budget alerts fire once when thresholds are crossed (with hysteresis so they don't nag), and a live cost readout sits in the footer status bar.

Install

pi install npm:pi-cost-tracker

Or try it once:

pi -e npm:pi-cost-tracker

Commands

| Command | Description | |---|---| | /cost | Session report: totals by bucket, per-model, last 15 turns, tool stats | | /cost-export | The same report as markdown, ready to paste | | /cost-history | Cross-session ledger summary (last 10 sessions) |

Configure

Optional, under a pi-cost-tracker key in ~/.pi/agent/settings.json (global) or .pi/settings.json (project; requires trust — project values merge over global):

{
  "pi-cost-tracker": {
    "sessionCostWarn": 2,
    "turnCostWarn": 0.25,
    "contextPercentWarn": 0.8
  }
}

| Option | Default | Fires when | |---|---|---| | sessionCostWarn | 1 | Cumulative session cost (USD) crosses this | | turnCostWarn | 0.25 | A single turn's cost (USD) crosses this | | contextPercentWarn | 0.8 | Context usage exceeds this fraction of the window |

How it works

pi-cost-tracker is a passive listener — it never modifies messages, blocks tools, or makes LLM calls of its own.

message_end (user)  → open a user turn with the triggering prompt
message_end         → attribute assistant usage → turn + per-model
tool_result         → nested LLM usage (tools that call models) → turn-nested bucket
tool_execution_end  → tool call counts / errors
session_compact     → compaction summary usage → compaction bucket
turn_end            → budget checks + footer status update
session_shutdown    → update this session's ledger snapshot

Usage arriving before any turn_start (e.g. a resumed session mid-run) lands in a synthetic (resumed) turn so nothing is lost. Cost figures come from each model's catalog pricing in pi; when a provider reports no cost, only token counts are tracked.

Development

npm install
npm run typecheck   # tsc --noEmit (strict)
npm test            # vitest
npm run test:coverage
npm run test:e2e    # install npm tarball, launch real pi, exercise RPC workflows

All accounting logic (accumulator, budget watcher, ledger, report rendering) lives in src/ as pure functions with full unit-test coverage; extensions/index.ts is the thin event-handling shell.

The E2E suite installs an actual npm pack artifact, registers it with pi, and runs pi 0.85.1 as a subprocess. It covers real tool loops and nested model usage, multiple models, reports, budget alerts, compaction costs, settings trust, and session restart. A deterministic localhost HTTP/SSE service supplies model responses; tests need no API keys or paid model calls. CI runs the suite after unit coverage checks. Live provider billing and terminal rendering are outside this suite.

Configuration and the ledger follow pi's PI_CODING_AGENT_DIR override when set (default: ~/.pi/agent). Tests use temporary directories and remove them afterward. Reopening a session restores its accounting from the session file; shutdown replaces its previous ledger snapshot rather than counting it as another session.

To test both extensions together, with a local pi-compact checkout:

PI_COMPACT_PROJECT=/path/to/pi-compact node --test test/interop.test.mjs

License

MIT