feat: copilot-usage — local Copilot CLI session tracker

[microsasa]

Problem

GitHub's Copilot usage dashboard has significant delays (or gaps) in reporting CLI premium request consumption. For individual users (non-org/enterprise), there is no API to query usage. The local ~/.copilot/session-state/*/events.jsonl files contain rich, accurate usage data that is not surfaced anywhere.

Solution

CLI tool (copilot-usage) that parses local Copilot CLI session data and presents usage metrics in the terminal. Includes an interactive mode with automatic file-watching refresh.

Data Sources

Each session in ~/.copilot/session-state/{session-id}/ contains events.jsonl — one JSON event per line:

Event Type	Key Data
session.start	Session ID, start time, working directory, model
session.shutdown	totalPremiumRequests, totalApiDurationMs, modelMetrics (per-model tokens + request counts), codeChanges
session.resume	Indicates session was reopened after shutdown
assistant.message	outputTokens per response
assistant.turn_start	Model call count tracking
user.message	User prompt count
tool.execution_complete	Tool name, model used

Critical: Shutdown events are NOT cumulative. Each represents one lifecycle. Must SUM all shutdown events for accurate totals.

Commands

copilot-usage (no subcommand) — Interactive Mode

Interactive Rich dashboard with:

• Summary home view with numbered session list
• Session detail drill-down (enter session number)
• Cost breakdown view
• Manual refresh
• Auto-refresh via filesystem watching — any change in the session-state directory triggers a re-read with debounce

copilot-usage summary [--since DATE] [--until DATE] [--path PATH]

Totals panel, per-model breakdown, per-session table with premium requests, model calls, user messages, output tokens, and status (Active 🟢 / Completed).

copilot-usage session SESSION_ID [--path PATH]

Header panel, aggregate stats, shutdown cycles table, active period stats (for resumed sessions), recent event timeline. Session ID can be a prefix.

copilot-usage cost [--since DATE] [--until DATE] [--path PATH]

Per-session per-model cost breakdown: requests, premium cost, model calls, output tokens. Shows post-shutdown activity for resumed sessions. Grand total row.

copilot-usage live [--path PATH]

Active sessions only: session ID, name, model, running time (since last resume for resumed sessions), message count, output tokens, CWD.

Key Behaviors

1. Shutdown aggregation: SUM all shutdown events — each is one lifecycle, not cumulative
2. Active detection: Events after last shutdown → session is active (resumed)
3. Running time: Shows time since last resume, not original session start
4. Premium requests: Exact from shutdown data. N/A for active sessions without shutdown data. No estimation.
5. Historical vs Active separation: Historical section only includes sessions with shutdown data. Pure-active sessions appear only in Active section.
6. Graceful degradation: Malformed data skipped with warning. Unknown event types handled. Never crashes on unexpected data.
7. Parent --path: Group-level --path cascades to all subcommands.

Model Multiplier Reference

Model	Multiplier	Tier
Claude Opus 4.6 / 4.5	3×	Premium
Claude Opus 4.6 (1M context)	6×	Premium
Claude Sonnet 4.6 / 4.5 / 4	1×	Standard
Claude Haiku 4.5	0.33×	Light
GPT-5.4 / 5.2 / 5.1 / 5.x-Codex	1×	Standard
GPT-5.1-Codex-Mini	0.33×	Light
GPT-5-mini / GPT-4.1	0×	Free
Gemini 3 Pro	1×	Standard

Multipliers are reference data only — the tool reports raw counts from shutdown data, not estimated billing.