|
| 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