tscope

GitHub Copilot session token usage analyzer.

tscope is a command-line tool that reads your local Copilot CLI session files, measures tokens used per model (input, output, cache read, cache write), and displays a clear report — in the terminal, as JSON, or as an interactive HTML dashboard.

Quick Start

npm install -g tscope
tscope --html # generate and open an HTML dashboard

Requires Node.js 18+.

HTML Dashboard Preview

The --html dashboard follows your system's light/dark theme:

Click the image to view it full size.

Generated from synthetic sample data.

Features

• 📊 Local-only analysis — no network calls, no credentials needed; OTel data is read from ~/.copilot/tscope/otel.jsonl
• 🔍 Per-session breakdown — view token usage by session and model
• 💰 Per-session cost — uses complete shutdown totals and per-model credits when available, while retaining OTel token and trace detail
• 📅 Recent-by-default — shows the 20 most recent sessions by default
• 📈 HTML dashboard — friendly session names, click-to-copy resume commands, token charts, sort controls, CSV export, and system light/dark theme
• 💡 Chronicle Insights — if a session ran /chronicle tips or /chronicle cost-tips, the recommendations are surfaced in the HTML dashboard
• 📤 JSON output — machine-readable schema (tscope/report/v8) for scripting

Data Sources

tscope reads from local sources with intelligent merging in default mode:

| Mode | Behavior | Cost | |---|---|---| | --source auto (default) | Reads OTel (~/.copilot/tscope/otel.jsonl) and log-parser sessions (~/.copilot/session-state/) into a merged report. On overlap, OTel supplies tokens/traces while the matching shutdown log supplies complete session/per-model credits and exact API time when present. | ✅ Complete shutdown credits with OTel detail | | --source otel | Reads only OTel data; exits with a helpful error if the file is absent or empty. | ✅ Server-side credits per session/model | | --source logs | Reads only log-parser sessions. Shows session/per-model credits and exact API time when shutdown fields are present. | ✅ Shutdown credits (Copilot CLI 1.0+) |

When OTel is not configured, auto falls back gracefully and prints a notice:

No OpenTelemetry data found — falling back to log-file parsing.
Run 'tscope otel enable' to use OTel.

OTel data is read entirely from disk — no network calls are made.

Command-Line Parameters

| Parameter | Values | Description | Required | | --- | --- | --- | --- | | --all | (none) | Include all sessions (disables the default 20-session cap). | No | | --date | YYYY-MM-DD | Show sessions that started on the given local date. | No | | --help, -h | (none) | Show usage and options, then exit. | No | | --html | [FILE] (optional path) | Write a self-contained HTML dashboard to FILE (or a default filename) and open it. | No | | --json | (none) | Emit the report as JSON (tscope/report/v8) to stdout instead of formatted text. | No | | --lastdays | N (positive integer) | Show sessions from the last N days (today plus the previous N − 1). | No | | --max | N (positive integer) | After date filtering, keep only the N most recent sessions (ordered by start time, newest first). | No | | --range | START END (two YYYY-MM-DD values) | Show sessions in the given local-date range, inclusive. | No | | --source | auto | otel | logs | Data source. auto (default): merges OTel and logs field-by-field on overlap. otel: OTel only; exits with error if unavailable. logs: log parser only. | No | | --version, -v | (none) | Print the installed version and exit. | No |

With no flags, tscope reports the 20 most recent sessions in formatted text. Date filters (--date, --range, --lastdays, --all) are mutually exclusive, and explicit --max overrides the default cap. See Usage for full details.

Documentation

Full documentation lives in the docs/ folder:

• Installation
• Usage — CLI flags, date filtering, output formats, sample output
• How It Works — session discovery, token accounting, resumed sessions
• JSON Output — tscope/report/v8 schema reference
• HTML Dashboard — dashboard features, Chronicle Insights, sort controls, CSV export
• OTel Setup — enable, disable, and inspect the OpenTelemetry file exporter
• Development — build, test, lint, project structure
• Contributing — roadmap, license

License

MIT.

Built with ❤️ for developers optimizing their Copilot CLI usage.