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