Skip to content

Commit ea4cac0

Browse files
jay-tauCopilot
andcommitted
docs(copilot): add documentation for @ccusage/copilot
Co-authored-by: Copilot <[email protected]>
1 parent aef0111 commit ea4cac0

6 files changed

Lines changed: 352 additions & 0 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+
```
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

‎docs/.vitepress/config.ts‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -88,6 +88,10 @@ export default defineConfig({
8888
text: 'OpenCode (Beta)',
8989
items: [{ text: 'Overview', link: '/guide/opencode/' }],
9090
},
91+
{
92+
text: 'Copilot CLI',
93+
items: [{ text: 'Overview', link: '/guide/copilot/' }],
94+
},
9195
{
9296
text: 'Configuration',
9397
items: [

‎docs/guide/copilot/index.md‎

Lines changed: 161 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,161 @@
1+
# Copilot CLI Overview
2+
3+
The `@ccusage/copilot` package analyzes [GitHub Copilot CLI](https://docs.github.com/en/copilot/github-copilot-in-the-cli) session usage, tracking token counts and costs across both Claude and GPT models.
4+
5+
## What is Copilot CLI?
6+
7+
GitHub Copilot CLI is a terminal-based AI coding agent that supports multiple model providers (Anthropic Claude, OpenAI GPT). The `@ccusage/copilot` package reads the local session data to give you a clear view of your usage.
8+
9+
## Installation & Launch
10+
11+
```bash
12+
# Recommended - always include @latest
13+
npx @ccusage/copilot@latest --help
14+
bunx @ccusage/copilot@latest --help # ⚠️ MUST include @latest with bunx
15+
16+
# Alternative package runners
17+
pnpm dlx @ccusage/copilot --help
18+
pnpx @ccusage/copilot --help
19+
```
20+
21+
::: warning ⚠️ Critical for bunx users
22+
Bun's bunx prioritizes binaries matching the package name suffix when given a scoped package. **Always use `bunx @ccusage/copilot@latest` with the version tag** to force bunx to fetch and run the correct package.
23+
:::
24+
25+
### Recommended: Shell Alias
26+
27+
Since `npx @ccusage/copilot@latest` is quite long to type repeatedly, we strongly recommend setting up a shell alias for convenience:
28+
29+
```bash
30+
# bash/zsh: alias ccusage-copilot='bunx @ccusage/copilot@latest'
31+
# fish: alias ccusage-copilot 'bunx @ccusage/copilot@latest'
32+
33+
# Then simply run:
34+
ccusage-copilot daily
35+
ccusage-copilot monthly --json
36+
```
37+
38+
::: tip
39+
After adding the alias to your shell config file (`.bashrc`, `.zshrc`, or `config.fish`), restart your shell or run `source` on the config file to apply the changes.
40+
:::
41+
42+
## Commands
43+
44+
### Daily Report
45+
46+
```bash
47+
ccusage-copilot daily # Table output
48+
ccusage-copilot daily --json # JSON output
49+
ccusage-copilot daily --compact # Compact table for narrow terminals
50+
```
51+
52+
### Monthly Report
53+
54+
```bash
55+
ccusage-copilot monthly
56+
ccusage-copilot monthly --json
57+
```
58+
59+
### Session Report
60+
61+
```bash
62+
ccusage-copilot session # Grouped by session with repository context
63+
ccusage-copilot session --json
64+
```
65+
66+
## Pricing Modes
67+
68+
Use `--mode` to control how costs are calculated:
69+
70+
```bash
71+
ccusage-copilot daily --mode premium # Default: premium request pricing
72+
ccusage-copilot daily --mode api # API-equivalent pricing
73+
```
74+
75+
### Premium Mode (Default)
76+
77+
Calculates cost using GitHub Copilot's premium request system: `premiumRequestCost × $0.04` (overage rate). The `requests.cost` field from Copilot data already includes model multipliers (e.g., Opus 4.7 = 7.5×, Sonnet = 1×, Haiku = 0.33×).
78+
79+
### API Mode
80+
81+
Calculates the hypothetical cost if the same tokens were used through Anthropic/OpenAI APIs directly. Uses official pricing from LiteLLM's pricing database. Useful for understanding the value of your Copilot subscription.
82+
83+
::: info
84+
JSON output always includes both `premiumCostUSD` and `apiCostUSD` regardless of selected mode.
85+
:::
86+
87+
## Data Source
88+
89+
Copilot CLI stores session data at `~/.copilot/session-state/`. Each session directory contains an `events.jsonl` file with JSON Lines events. Usage data is extracted from:
90+
91+
- **`session.start`** — Session metadata (cwd, repository, branch, copilotVersion)
92+
- **`session.shutdown`** — Per-model aggregated token metrics (inputTokens, outputTokens, cacheReadTokens, cacheWriteTokens, premium request counts)
93+
94+
## Additional Options
95+
96+
### Date Filtering
97+
98+
```bash
99+
ccusage-copilot daily --since 2026-04-01 --until 2026-04-30
100+
ccusage-copilot monthly --since 2026-04 --until 2026-04
101+
```
102+
103+
Accepts `YYYY-MM-DD` or `YYYYMMDD` format. For monthly reports, dates are truncated to month.
104+
105+
### Timezone
106+
107+
```bash
108+
ccusage-copilot daily --timezone America/New_York
109+
ccusage-copilot daily -z Asia/Kolkata
110+
```
111+
112+
Controls which calendar day/month events are grouped into. Defaults to your system timezone.
113+
114+
### Sort Order
115+
116+
```bash
117+
ccusage-copilot daily --order desc # Most recent first
118+
ccusage-copilot session --order asc # Oldest first (default)
119+
```
120+
121+
### Model Breakdown
122+
123+
```bash
124+
ccusage-copilot daily --breakdown --mode api
125+
```
126+
127+
Shows per-model token and cost breakdown beneath each row.
128+
129+
### Offline Pricing
130+
131+
```bash
132+
ccusage-copilot daily --mode api --offline
133+
```
134+
135+
Uses build-time cached pricing data instead of fetching from LiteLLM.
136+
137+
### Color Control
138+
139+
```bash
140+
ccusage-copilot daily --color # Force colors
141+
ccusage-copilot daily --no-color # Disable colors
142+
```
143+
144+
Colors are auto-detected by default. Also respects `FORCE_COLOR=1` and `NO_COLOR=1` environment variables.
145+
146+
## Supported Models
147+
148+
The package supports all models available in Copilot CLI:
149+
150+
- **Claude**: claude-haiku-4.5, claude-sonnet-4/4.5/4.6, claude-opus-4.5/4.6/4.6-1m/4.7
151+
- **GPT**: gpt-5.1, gpt-5.2, gpt-5.4
152+
- **Other**: goldeneye
153+
154+
Model names are automatically normalized for LiteLLM pricing lookup (e.g., `claude-opus-4.6` → `claude-opus-4-6`).
155+
156+
## Environment Variables
157+
158+
| Variable | Description | Default |
159+
| -------------------- | -------------------------------------- | ------------ |
160+
| `COPILOT_CONFIG_DIR` | Override Copilot data directory | `~/.copilot` |
161+
| `LOG_LEVEL` | Logging verbosity (0=silent … 5=trace) | — |

0 commit comments

Comments
 (0)