copilot-usage

CLI and TypeScript library for analyzing GitHub Copilot CLI token usage, premium requests, and API-equivalent costs from local and Codespaces logs.

This project is a TypeScript migration and extension of the original Go project ekroon/copilot-token-cost. The bundled historical pricing data is kept aligned with that upstream source while the TS package exposes both a CLI and reusable library APIs.

Features

• Parse Copilot CLI logs and session state data
• Track prompt, completion, cache-read, and cache-write tokens
• Calculate historical API-equivalent costs using timestamp-aware pricing
• Estimate premium request usage by model and day
• Store parsed data in SQLite for fast repeated queries
• Import/export JSONL and SQLite snapshots
• Sync data from GitHub Codespaces
• Serve a local web dashboard with live updates

Install

Requires Node.js >= 18.

Global CLI install

npm install -g copilot-usage
copilot-usage --help

One-off usage with npx

npx copilot-usage --help
npx copilot-usage --json

Library usage

npm install copilot-usage

CLI quick start

# Default: last 7 days
copilot-usage
npx copilot-usage

# Last 30 days
copilot-usage 30
npx copilot-usage 30

# Machine-readable JSON
copilot-usage --json
npx copilot-usage --json

# Start the web dashboard
copilot-usage --web
npx copilot-usage --web

Programmatic usage

import {
  ParseLogContent,
  Stats,
  calcCost,
  getPremiumMultiplier,
  loadPricingPeriods
} from 'copilot-usage';

const pricing = loadPricingPeriods();
const records = ParseLogContent(logText, 'process.log');

for (const record of records) {
  const stats = new Stats();
  stats.addRecord(record, record.isUserTurn ? getPremiumMultiplier(pricing, record.model, record.timestamp) : 0);
  const cost = calcCost(pricing, record.model, stats, record.timestamp);
  console.log(record.model, cost);
}

You can also import the bundled historical pricing dataset directly:

import pricing from 'copilot-usage/pricing.json' with { type: 'json' };

Usage

copilot-usage [days] [flags]
copilot-usage sql [--json] "SQL QUERY"

For one-off runs without a global install, replace copilot-usage with npx copilot-usage in any example below.

Examples

copilot-usage                         # last 7 days (default)
copilot-usage 30                      # last 30 days
copilot-usage --period 30             # same, via explicit flag
copilot-usage --all                   # all available data
copilot-usage --today --json          # today only, JSON output
copilot-usage --yesterday             # yesterday only
copilot-usage --from 14 --to 7        # 14 days ago to 7 days ago
copilot-usage --project myapp         # filter by project name

copilot-usage --sync                  # force re-parse all logs
copilot-usage --export-file out.jsonl # export data as JSONL
copilot-usage --import-file in.jsonl  # import JSONL data
copilot-usage --import-file other.db  # import from another SQLite DB

copilot-usage --codespaces-sync       # sync from running Codespaces
copilot-usage --web                   # start web dashboard
copilot-usage --web --web-listen :8080 --web-local-streaming

SQL queries

Run read-only SQL queries directly against the local database:

copilot-usage sql "SELECT COUNT(*) FROM api_calls"
copilot-usage sql --json "SELECT model_normalized, COUNT(*) AS n FROM api_calls GROUP BY 1 ORDER BY n DESC"
copilot-usage sql "SELECT DISTINCT cwd FROM session_workspaces"
echo "SELECT MAX(timestamp) FROM api_calls" | copilot-usage sql

Flags

Date window

Flag	Description
<days>	Number of days to look back (default: 7)
--period VALUE	Explicit date window: today, yesterday, all, or a positive day count
--all	Process all available data
--today	Today only
--yesterday	Yesterday only
--from N	Start from N days ago (0=today)
--to N	End at N days ago (0=today)

Precedence: --all > --today > --yesterday > --period > positional

Data source

Flag	Description
--logs-dir PATH	Override Copilot logs directory (default: ~/.copilot/logs)
--sync	Force full re-sync of all log files
--import-file FILE	Import data from .jsonl or .db/.sqlite file
--export-file FILE	Export data as JSONL
--codespaces-sync	Sync Copilot data from running Codespaces via gh cs cp
--codespaces-include-stopped	Include stopped Codespaces (requires --codespaces-sync or --web)

Output

Flag	Description
--json	Machine-readable JSON output
--project TEXT	Filter stats by project name (substring match, case-insensitive)

Web dashboard

Flag	Default	Description
--web	—	Run local web dashboard
--web-listen ADDR	127.0.0.1:7331	Listen address (e.g. :8080, 0.0.0.0:3000)
--web-refresh-interval DURATION	30s	Local refresh interval
--web-local-streaming	—	Realtime local log streaming
--web-codespaces-mode MODE	auto	manual or auto
--web-codespaces-streaming	—	Live Codespaces streaming checkpoint status
--web-codespaces-interval DURATION	5m	Codespaces sync interval (auto mode)
--web-log-mode MODE	compact	compact, verbose, or errors

Web mode

copilot-usage --web
copilot-usage --web --today
copilot-usage --web --web-local-streaming
copilot-usage --web --web-codespaces-mode manual
copilot-usage --web --web-log-mode verbose

Web mode serves a Datastar-driven dashboard with live SSE updates.

Endpoints

Endpoint	Method	Description
/	GET	Copilot Stats view (today + weekly, trends, top projects/models)
/details	GET	Detailed dashboard with summary tables and JSON snapshot
/events	GET	Persistent SSE stream for live patch broadcasts
/api/stats	GET	Current JSON stats snapshot
/healthz	GET	Liveness check (ok)
/actions/sync-codespaces	POST	Trigger Codespaces sync
/actions/project-row	POST	Expand/collapse project row
/actions/day-row	POST	Expand/collapse day row

SQLite database

Token data is stored in a SQLite database at:

• $XDG_STATE_HOME/copilot-usage/copilot-tokens.db when XDG_STATE_HOME is set
• ~/.local/state/copilot-usage/copilot-tokens.db as fallback

The database:

• Auto-syncs on every run
• Skips already parsed log files on subsequent runs
• Supports import/export workflows
• Stores both local and Codespaces-derived usage data

Historical pricing

The bundled pricing.json contains time-ranged pricing periods. Each API call is costed using the pricing in effect at its timestamp, so historical recalculations stay accurate when model pricing or premium multipliers change over time.

Token prices are stored in USD per 1M tokens and premium request pricing is stored per premium request.

Development

npm install
npm run typecheck
npm run test
npm run build

Pack preview

Before publishing, inspect the npm tarball contents locally:

npm pack --dry-run

Source install

git clone https://github.com/tayor/copilot-usage.git
cd copilot-usage
npm install
npm run build
node dist/cli/main.js --help

Attribution

• Original Go implementation: ekroon/copilot-token-cost
• This package is a TypeScript migration and derivative work built for npm distribution
• Historical pricing updates are synced against the upstream Go project