Skip to content

Commit a61c0ac

Browse files
jay-tauCopilot
andcommitted
docs(copilot): add documentation for @ccusage/copilot
- apps/copilot/README.md: badges, quick start, usage, dual pricing - apps/copilot/CLAUDE.md: developer notes on data format and models - Root README.md + CLAUDE.md: add to ccusage Family listing - docs/guide/copilot/index.md: VitePress guide with all commands/flags - docs/.vitepress/config.ts: sidebar entry Co-authored-by: Copilot <[email protected]>
1 parent 29e1634 commit a61c0ac

14 files changed

Lines changed: 399 additions & 137 deletions

File tree

‎CLAUDE.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,7 @@ This is a monorepo containing multiple packages. For package-specific guidance,
99
- **Main CLI Package**: @apps/ccusage/CLAUDE.md - Core ccusage CLI tool and library
1010
- **Codex CLI Package**: @apps/codex/CLAUDE.md - OpenAI Codex usage tracking CLI
1111
- **OpenCode CLI Package**: @apps/opencode/CLAUDE.md - OpenCode usage tracking CLI
12+
- **Copilot CLI Package**: @apps/copilot/CLAUDE.md - GitHub Copilot CLI usage tracking
1213
- **MCP Server Package**: @apps/mcp/CLAUDE.md - MCP server implementation for ccusage data
1314
- **Documentation**: @docs/CLAUDE.md - VitePress-based documentation website
1415

‎apps/ccusage/README.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -41,6 +41,10 @@ Companion tool for analyzing [pi-agent](https://github.com/badlogic/pi-mono) ses
4141

4242
Companion tool for analyzing [Amp](https://ampcode.com/) session usage. Track token usage, costs, and credits from your Amp CLI sessions with daily, monthly, and session-based reports.
4343

44+
### 🤖 [@ccusage/copilot](https://www.npmjs.com/package/@ccusage/copilot) - GitHub Copilot CLI Usage Analyzer
45+
46+
Companion tool for analyzing [GitHub Copilot CLI](https://docs.github.com/en/copilot/github-copilot-in-the-cli) session usage. Track token usage and costs with dual pricing modes: premium request costs or API-equivalent rates.
47+
4448
### 🔌 [@ccusage/mcp](https://www.npmjs.com/package/@ccusage/mcp) - MCP Server Integration
4549

4650
Model Context Protocol server that exposes ccusage data to Claude Desktop and other MCP-compatible tools. Enable real-time usage tracking directly in your AI workflows.
@@ -73,6 +77,7 @@ npx @ccusage/codex@latest # OpenAI Codex usage tracking
7377
npx @ccusage/opencode@latest # OpenCode usage tracking
7478
npx @ccusage/pi@latest # Pi-agent usage tracking
7579
npx @ccusage/amp@latest # Amp usage tracking
80+
npx @ccusage/copilot@latest # GitHub Copilot CLI usage tracking
7681
npx @ccusage/mcp@latest # MCP Server
7782
```
7883

‎apps/copilot/CLAUDE.md‎

Lines changed: 64 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,64 @@
1+
# Copilot CLI Notes
2+
3+
## Log Sources
4+
5+
- Copilot CLI session data is stored under `${COPILOT_CONFIG_DIR:-~/.copilot}/session-state/`.
6+
- Each session is stored as a directory named with the session UUID (e.g., `session-state/{uuid}/`).
7+
- Usage data is extracted from `events.jsonl` files within each session directory.
8+
- Session metadata is available from `session.start` events and `workspace.yaml` files.
9+
10+
## Data Format
11+
12+
- `events.jsonl`: JSON Lines format, one event per line.
13+
- Key event types:
14+
- `session.start` — session metadata (sessionId, copilotVersion, startTime, context)
15+
- `session.shutdown` — aggregated per-model token metrics (primary usage data source)
16+
- `session.resume` — session resume marker
17+
- `assistant.usage` — per-request usage (ephemeral, NOT persisted to disk)
18+
19+
## Token Fields (from session.shutdown modelMetrics)
20+
21+
- `inputTokens`: total input tokens sent to the model.
22+
- `outputTokens`: output tokens (completion text).
23+
- `cacheReadTokens`: tokens read from cache.
24+
- `cacheWriteTokens`: tokens written to cache.
25+
- `totalTokens`: sum of all token types.
26+
27+
## Premium Requests
28+
29+
- Copilot CLI tracks costs as premium request counts (not USD directly).
30+
- Each model's `requests.cost` represents the number of premium requests consumed.
31+
- `requests.count` is the total number of API requests made to that model.
32+
- `totalPremiumRequests` in shutdown data is the session-wide premium request total.
33+
34+
## Models
35+
36+
Copilot CLI supports both Anthropic Claude and OpenAI GPT models:
37+
38+
- Claude: claude-haiku-4.5, claude-sonnet-4, claude-sonnet-4.5, claude-sonnet-4.6, claude-opus-4.5, claude-opus-4.6, claude-opus-4.6-1m, claude-opus-4.7
39+
- GPT: gpt-5.1, gpt-5.2, gpt-5.4
40+
- Other: goldeneye
41+
42+
## Cost Calculation
43+
44+
- Pricing is pulled from LiteLLM's public JSON (`model_prices_and_context_window.json`).
45+
- Both Claude and GPT model pricing prefixes are supported.
46+
- Cost formula per model:
47+
- Input: `inputTokens / 1_000_000 * input_cost_per_mtoken`
48+
- Cached input read: `cacheReadTokens / 1_000_000 * cached_input_cost_per_mtoken`
49+
- Cache creation: `cacheWriteTokens / 1_000_000 * cache_creation_cost_per_mtoken`
50+
- Output: `outputTokens / 1_000_000 * output_cost_per_mtoken`
51+
52+
## CLI Usage
53+
54+
- Treat Copilot as a sibling to `apps/ccusage`, `apps/codex`, `apps/amp`, etc.
55+
- Reuse shared packages (`@ccusage/terminal`, `@ccusage/internal`) wherever possible.
56+
- Copilot is packaged as a bundled CLI. Keep every runtime dependency in `devDependencies`.
57+
- Entry point uses Gunshi framework with subcommands: `daily`, `monthly`, `session`.
58+
- Shared args defined in `_shared-args.ts` (json, since, until, timezone, locale, offline, compact, mode, order, breakdown, color/noColor).
59+
- Date utilities in `_date-utils.ts` (timezone-aware grouping, date filtering).
60+
- Data discovery relies on `COPILOT_CONFIG_DIR` environment variable.
61+
62+
## Environment Variables
63+
64+
- `COPILOT_CONFIG_DIR` — override default Copilot data directory (default: `~/.copilot`)

‎apps/copilot/README.md‎

Lines changed: 117 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,117 @@
1+
<div align="center">
2+
<img src="https://cdn.jsdelivr.net/gh/ryoppippi/ccusage@main/docs/public/logo.svg" alt="ccusage logo" width="256" height="256">
3+
<h1>@ccusage/copilot</h1>
4+
</div>
5+
6+
<p align="center">
7+
<a href="https://socket.dev/api/npm/package/@ccusage/copilot"><img src="https://socket.dev/api/badge/npm/package/@ccusage/copilot" alt="Socket Badge" /></a>
8+
<a href="https://npmjs.com/package/@ccusage/copilot"><img src="https://img.shields.io/npm/v/@ccusage/copilot?color=yellow" alt="npm version" /></a>
9+
<a href="https://packagephobia.com/result?p=@ccusage/copilot"><img src="https://packagephobia.com/badge?p=@ccusage/copilot" alt="install size" /></a>
10+
<a href="https://deepwiki.com/ryoppippi/ccusage"><img src="https://img.shields.io/badge/DeepWiki-ryoppippi%2Fccusage-blue.svg?logo=data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAACwAAAAyCAYAAAAnWDnqAAAAAXNSR0IArs4c6QAAA05JREFUaEPtmUtyEzEQhtWTQyQLHNak2AB7ZnyXZMEjXMGeK/AIi+QuHrMnbChYY7MIh8g01fJoopFb0uhhEqqcbWTp06/uv1saEDv4O3n3dV60RfP947Mm9/SQc0ICFQgzfc4CYZoTPAswgSJCCUJUnAAoRHOAUOcATwbmVLWdGoH//PB8mnKqScAhsD0kYP3j/Yt5LPQe2KvcXmGvRHcDnpxfL2zOYJ1mFwrryWTz0advv1Ut4CJgf5uhDuDj5eUcAUoahrdY/56ebRWeraTjMt/00Sh3UDtjgHtQNHwcRGOC98BJEAEymycmYcWwOprTgcB6VZ5JK5TAJ+fXGLBm3FDAmn6oPPjR4rKCAoJCal2eAiQp2x0vxTPB3ALO2CRkwmDy5WohzBDwSEFKRwPbknEggCPB/imwrycgxX2NzoMCHhPkDwqYMr9tRcP5qNrMZHkVnOjRMWwLCcr8ohBVb1OMjxLwGCvjTikrsBOiA6fNyCrm8V1rP93iVPpwaE+gO0SsWmPiXB+jikdf6SizrT5qKasx5j8ABbHpFTx+vFXp9EnYQmLx02h1QTTrl6eDqxLnGjporxl3NL3agEvXdT0WmEost648sQOYAeJS9Q7bfUVoMGnjo4AZdUMQku50McDcMWcBPvr0SzbTAFDfvJqwLzgxwATnCgnp4wDl6Aa+Ax283gghmj+vj7feE2KBBRMW3FzOpLOADl0Isb5587h/U4gGvkt5v60Z1VLG8BhYjbzRwyQZemwAd6cCR5/XFWLYZRIMpX39AR0tjaGGiGzLVyhse5C9RKC6ai42ppWPKiBagOvaYk8lO7DajerabOZP46Lby5wKjw1HCRx7p9sVMOWGzb/vA1hwiWc6jm3MvQDTogQkiqIhJV0nBQBTU+3okKCFDy9WwferkHjtxib7t3xIUQtHxnIwtx4mpg26/HfwVNVDb4oI9RHmx5WGelRVlrtiw43zboCLaxv46AZeB3IlTkwouebTr1y2NjSpHz68WNFjHvupy3q8TFn3Hos2IAk4Ju5dCo8B3wP7VPr/FGaKiG+T+v+TQqIrOqMTL1VdWV1DdmcbO8KXBz6esmYWYKPwDL5b5FA1a0hwapHiom0r/cKaoqr+27/XcrS5UwSMbQAAAABJRU5ErkJggg==" alt="DeepWiki"></a>
11+
</p>
12+
13+
> Analyze [GitHub Copilot CLI](https://docs.github.com/en/copilot/github-copilot-in-the-cli) usage logs with the same reporting experience as `ccusage`.
14+
15+
## Quick Start
16+
17+
```bash
18+
# Recommended - always include @latest
19+
npx @ccusage/copilot@latest --help
20+
bunx @ccusage/copilot@latest --help # ⚠️ MUST include @latest with bunx
21+
22+
# Alternative package runners
23+
pnpm dlx @ccusage/copilot
24+
pnpx @ccusage/copilot
25+
```
26+
27+
### Recommended: Shell Alias
28+
29+
Since `npx @ccusage/copilot@latest` is quite long to type repeatedly, we strongly recommend setting up a shell alias:
30+
31+
```bash
32+
# bash/zsh: alias ccusage-copilot='bunx @ccusage/copilot@latest'
33+
# fish: alias ccusage-copilot 'bunx @ccusage/copilot@latest'
34+
35+
# Then simply run:
36+
ccusage-copilot daily
37+
ccusage-copilot monthly --json
38+
```
39+
40+
## Usage
41+
42+
```bash
43+
# Daily usage report (default command)
44+
ccusage-copilot daily
45+
46+
# Monthly summary
47+
ccusage-copilot monthly
48+
49+
# Per-session breakdown
50+
ccusage-copilot session
51+
52+
# JSON output
53+
ccusage-copilot daily --json
54+
55+
# Compact table for narrow terminals
56+
ccusage-copilot daily --compact
57+
58+
# Filter by date range
59+
ccusage-copilot daily --since 2026-04-01 --until 2026-04-30
60+
61+
# Reverse sort order
62+
ccusage-copilot daily --order desc
63+
64+
# Show per-model breakdown
65+
ccusage-copilot daily --breakdown --mode api
66+
67+
# Use specific timezone
68+
ccusage-copilot daily --timezone America/New_York
69+
70+
# Use cached pricing (offline)
71+
ccusage-copilot daily --mode api --offline
72+
```
73+
74+
## Pricing Modes
75+
76+
Use `--mode` to control how costs are calculated:
77+
78+
```bash
79+
# Premium request pricing (default) — what you actually pay on Copilot
80+
ccusage-copilot daily --mode premium
81+
82+
# API-equivalent pricing — what it would cost at Anthropic/OpenAI API rates
83+
ccusage-copilot daily --mode api
84+
```
85+
86+
- **`premium`** (default): Uses GitHub Copilot's premium request counts × $0.04 (overage rate). The `requests.cost` field already includes model multipliers.
87+
- **`api`**: Calculates hypothetical costs using official Anthropic/OpenAI API rates via LiteLLM. Useful for understanding the value of your Copilot subscription.
88+
89+
JSON output always includes both `premiumCostUSD` and `apiCostUSD` regardless of selected mode.
90+
91+
## Data Source
92+
93+
Copilot CLI stores session data at:
94+
95+
```text
96+
~/.copilot/
97+
session-state/
98+
{sessionId}/ # UUID directory per session
99+
events.jsonl # JSON Lines event stream
100+
workspace.yaml # session metadata
101+
```
102+
103+
## Environment Variables
104+
105+
- `COPILOT_CONFIG_DIR` — override the base Copilot directory (default: `~/.copilot`)
106+
- `LOG_LEVEL` — control logging verbosity (0=silent … 5=trace)
107+
108+
## Related
109+
110+
Part of the [ccusage](https://github.com/ryoppippi/ccusage) family:
111+
112+
- [`ccusage`](https://www.npmjs.com/package/ccusage) — Claude Code usage
113+
- [`@ccusage/codex`](https://www.npmjs.com/package/@ccusage/codex) — OpenAI Codex usage
114+
- [`@ccusage/opencode`](https://www.npmjs.com/package/@ccusage/opencode) — OpenCode usage
115+
- [`@ccusage/pi`](https://www.npmjs.com/package/@ccusage/pi) — Pi-agent usage
116+
- [`@ccusage/amp`](https://www.npmjs.com/package/@ccusage/amp) — Amp usage
117+
- [`@ccusage/copilot`](https://www.npmjs.com/package/@ccusage/copilot) — GitHub Copilot CLI usage

‎apps/copilot/package.json‎

Lines changed: 39 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1,34 +1,64 @@
11
{
22
"name": "@ccusage/copilot",
3+
"type": "module",
34
"version": "18.0.11",
45
"description": "Usage analysis tool for GitHub Copilot CLI sessions",
5-
"homepage": "https://github.com/ryoppippi/ccusage#readme",
6-
"bugs": {
7-
"url": "https://github.com/ryoppippi/ccusage/issues"
8-
},
9-
"license": "MIT",
106
"author": "ryoppippi",
7+
"license": "MIT",
8+
"funding": "https://github.com/ryoppippi/ccusage?sponsor=1",
9+
"homepage": "https://github.com/ryoppippi/ccusage#readme",
1110
"repository": {
1211
"type": "git",
1312
"url": "git+https://github.com/ryoppippi/ccusage.git",
1413
"directory": "apps/copilot"
1514
},
16-
"funding": "https://github.com/ryoppippi/ccusage?sponsor=1",
15+
"bugs": {
16+
"url": "https://github.com/ryoppippi/ccusage/issues"
17+
},
18+
"main": "./dist/index.js",
19+
"module": "./dist/index.js",
1720
"bin": {
1821
"ccusage-copilot": "./src/index.ts"
1922
},
2023
"files": [
2124
"dist"
2225
],
23-
"type": "module",
24-
"main": "./dist/index.js",
25-
"module": "./dist/index.js",
2626
"publishConfig": {
2727
"bin": {
2828
"ccusage-copilot": "./dist/index.js"
2929
}
3030
},
3131
"engines": {
3232
"node": ">=20.19.4"
33+
},
34+
"scripts": {
35+
"build": "tsdown",
36+
"format": "pnpm run lint --fix",
37+
"lint": "eslint --cache .",
38+
"prepack": "pnpm run build && clean-pkg-json",
39+
"prerelease": "pnpm run lint && pnpm run typecheck && pnpm run build",
40+
"start": "bun ./src/index.ts",
41+
"test": "TZ=UTC vitest",
42+
"typecheck": "tsgo --noEmit"
43+
},
44+
"devDependencies": {
45+
"@ccusage/internal": "workspace:*",
46+
"@ccusage/terminal": "workspace:*",
47+
"@praha/byethrow": "catalog:runtime",
48+
"@ryoppippi/eslint-config": "catalog:lint",
49+
"@typescript/native-preview": "catalog:types",
50+
"clean-pkg-json": "catalog:release",
51+
"eslint": "catalog:lint",
52+
"fast-sort": "catalog:runtime",
53+
"fs-fixture": "catalog:testing",
54+
"gunshi": "catalog:runtime",
55+
"path-type": "catalog:runtime",
56+
"picocolors": "catalog:runtime",
57+
"tinyglobby": "catalog:runtime",
58+
"tsdown": "catalog:build",
59+
"unplugin-macros": "catalog:build",
60+
"unplugin-unused": "catalog:build",
61+
"valibot": "catalog:runtime",
62+
"vitest": "catalog:testing"
3363
}
3464
}

‎apps/copilot/src/_date-utils.ts‎

Lines changed: 0 additions & 31 deletions
Original file line numberDiff line numberDiff line change
@@ -92,37 +92,6 @@ export function isWithinRange(dateKey: string, since?: string, until?: string):
9292
return true;
9393
}
9494

95-
/**
96-
* Format a date key for display using locale
97-
*/
98-
export function formatDisplayDate(dateKey: string, locale?: string, timezone?: string): string {
99-
const tz = safeTimeZone(timezone);
100-
const date = new Date(`${dateKey}T00:00:00`);
101-
const formatter = new Intl.DateTimeFormat(locale ?? 'en-US', {
102-
year: 'numeric',
103-
month: 'short',
104-
day: 'numeric',
105-
timeZone: tz,
106-
});
107-
return formatter.format(date);
108-
}
109-
110-
/**
111-
* Format a month key for display using locale
112-
*/
113-
export function formatDisplayMonth(monthKey: string, locale?: string): string {
114-
const [yearStr = '0', monthStr = '1'] = monthKey.split('-');
115-
const year = Number.parseInt(yearStr, 10);
116-
const month = Number.parseInt(monthStr, 10);
117-
const date = new Date(Date.UTC(year, month - 1, 1));
118-
const formatter = new Intl.DateTimeFormat(locale ?? 'en-US', {
119-
year: 'numeric',
120-
month: 'short',
121-
timeZone: 'UTC',
122-
});
123-
return formatter.format(date);
124-
}
125-
12695
if (import.meta.vitest != null) {
12796
describe('normalizeFilterDate', () => {
12897
it('normalizes YYYYMMDD to YYYY-MM-DD', () => {

‎apps/copilot/src/_shared-args.ts‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -11,12 +11,12 @@ export const sharedArgs = {
1111
since: {
1212
type: 'string',
1313
short: 's',
14-
description: 'Filter from date (YYYY-MM-DD or YYYYMMDD)',
14+
description: 'Filter from date (YYYY-MM, YYYY-MM-DD, or YYYYMMDD)',
1515
},
1616
until: {
1717
type: 'string',
1818
short: 'u',
19-
description: 'Filter until date (inclusive)',
19+
description: 'Filter until date (inclusive, YYYY-MM, YYYY-MM-DD, or YYYYMMDD)',
2020
},
2121
timezone: {
2222
type: 'string',

0 commit comments

Comments
 (0)