pi-token-tracker

Pi extension that tracks per-call token usage across all sessions, including taskplane lane workers and merge agents.

How it works

• message_end hook: Writes one JSONL line per assistant response to ~/.pi/token-logs/usage.jsonl
• token-report command: Scans usage.jsonl + taskplane runtime exit summaries and prints a hierarchical vendor/model breakdown

Recorded Fields

Each JSONL record contains:

| Field | Description | |-------|-------------| | date, time | ISO date/timestamp | | provider, model | Model identifier (e.g., anthropic, claude-sonnet-4) | | inputTokens | Input token count | | outputTokens | Output token count | | cacheReadTokens | Cache read tokens (if supported) | | cacheWriteTokens | Cache write tokens (if supported) | | totalTokens | Sum of all token counts | | cost | Estimated cost in USD | | ttftMs | Time to First Token (ms) — from HTTP response headers to first streaming token | | tps | Tokens Per Second — output tokens / streaming duration |

Installation

# Clone and install
git clone https://github.com/skyscribe-yf/pi-token-tracker.git
cd pi-token-tracker
npm link

# Add to pi settings
# Edit ~/.pi/agent/settings.json and add "npm:pi-token-tracker" to the "packages" array:
# {
#   "packages": [
#     "npm:pi-token-tracker",
#     ...
#   ]
# }

Why a pi package?

Taskplane lane workers and merge agents run with --no-extensions, which prevents auto-discovery of user extensions from the working directory. However, taskplane's loadPiSettingsPackages mechanism automatically forwards pi packages (from settings.json) to worker processes as explicit -e flags.

By installing this extension as a pi package, it gets loaded in:

• Main pi sessions ✓
• Taskplane lane workers ✓
• Taskplane merge agents ✓

Safety in RPC mode

The extension is safe to load in headless RPC worker processes:

• session_start hook uses try-catch to handle missing UI
• token-report command uses try-catch for notify in UI-less contexts

License

MIT