{"id":50554793,"url":"https://github.com/damianedwards/copilot-cli-cost","last_synced_at":"2026-06-04T06:01:52.766Z","repository":{"id":356182818,"uuid":"1231407826","full_name":"DamianEdwards/copilot-cli-cost","owner":"DamianEdwards","description":"Copilot CLI extension that shows real-time estimated session cost.","archived":false,"fork":false,"pushed_at":"2026-05-27T19:24:56.000Z","size":4149,"stargazers_count":28,"open_issues_count":4,"forks_count":2,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-05-27T21:13:58.988Z","etag":null,"topics":["copilot-cli"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/DamianEdwards.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-06T23:52:22.000Z","updated_at":"2026-05-27T19:25:00.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/DamianEdwards/copilot-cli-cost","commit_stats":null,"previous_names":["damianedwards/copilot-cli-cost"],"tags_count":10,"template":false,"template_full_name":null,"purl":"pkg:github/DamianEdwards/copilot-cli-cost","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DamianEdwards%2Fcopilot-cli-cost","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DamianEdwards%2Fcopilot-cli-cost/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DamianEdwards%2Fcopilot-cli-cost/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DamianEdwards%2Fcopilot-cli-cost/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/DamianEdwards","download_url":"https://codeload.github.com/DamianEdwards/copilot-cli-cost/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DamianEdwards%2Fcopilot-cli-cost/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33891733,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-04T02:00:06.755Z","response_time":64,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["copilot-cli"],"created_at":"2026-06-04T06:01:51.488Z","updated_at":"2026-06-04T06:01:52.753Z","avatar_url":"https://github.com/DamianEdwards.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Copilot CLI Cost\n\nCopilot CLI Cost adds estimated session-cost reporting to GitHub Copilot CLI.\n\nIt estimates usage-based billing with GitHub AI Credits.\n\nThe calculator stores canonical cost in USD and converts to a selected display currency with cached exchange rates from Frankfurter or an explicit exchange-rate override.\n\n![Copilot Cost panel showing session estimates and token bucket breakdown](docs/session-cost-panel.png)\n\n## Features\n\n- `/cost` command for active-session estimates\n- `/cost session \u003csession-id\u003e` for completed local sessions\n- Native cost panel with token bucket breakdowns\n- What-if subscription comparison for Copilot Free, Pro, Pro+, Max, Business, Enterprise, and Student\n- Display currency selector backed by cached Frankfurter USD exchange rates\n- Statusline cost segment with optional passthrough to another statusline\n- Standalone calculator CLI for sample data, JSON files, completed session events, and live snapshots\n- USD-first cost model with optional display currency conversion\n\n## Install\n\nInstall by executing the install script for your platform.\n\nWindows PowerShell (`install.ps1`):\n\n```powershell\nirm https://raw.githubusercontent.com/DamianEdwards/copilot-cli-cost/main/install.ps1 | iex\n```\n\nmacOS/Linux (`install.sh`):\n\n```bash\nbash -c \"$(curl -fsSL https://raw.githubusercontent.com/DamianEdwards/copilot-cli-cost/main/install.sh)\"\n```\n\nThe remote scripts run in isolation and fetch their helper from the same raw-content base URL before configuring Copilot. To run the installer script from a checkout instead:\n\n```powershell\n.\\install.ps1\n```\n\n```bash\n./install.sh\n```\n\nThe installer:\n\n- On Copilot CLI 1.0.56-0 or newer, registers this repository's marketplace and installs or updates `copilot-cli-cost@copilot-cli-cost-marketplace`. Older Copilot CLI versions use the direct repository install format.\n- Downloads the installer helper from the raw-content base URL.\n- Installs the user-scoped extension shim for `/cost` and the panel.\n- Enables the Copilot experimental flags needed for extensions and the status line.\n- Configures a stable user-scoped statusline launcher under `~/.copilot/copilot-cli-cost/`.\n\nIf you already have a Copilot status line configured, the installer prompts you to replace it, decorate it with the Copilot Cost status line using passthrough mode, or skip statusline configuration. Before changing existing settings that would otherwise be overwritten, it prompts and writes a timestamped `settings.json.bak-*` backup.\n\nInstaller options:\n\n| Option | Description |\n| --- | --- |\n| `--plugin-source \u003csource\u003e` | Use a fork or alternate plugin source. On Copilot CLI 1.0.56-0 or newer, this must be a marketplace source. |\n| `--marketplace-name \u003cname\u003e` | Use a custom marketplace name when the marketplace metadata differs from `copilot-cli-cost-marketplace`. |\n| `--plugin-name \u003cname\u003e` | Use a custom plugin name when the marketplace metadata differs from `copilot-cli-cost`. |\n| `--copilot-home \u003cpath\u003e` | Use a custom Copilot home directory instead of `~/.copilot`; useful for isolated verification. |\n| `--skip-statusline` | Install the plugin and extension shim without configuring `statusLine`. |\n| `--yes` | Accept installer prompts. Existing status lines are decorated, not replaced. |\n\nSet `COPILOT_COST_PLUGIN_SOURCE` or pass `--plugin-source \u003csource\u003e` to install from a fork or alternate plugin source. On Copilot CLI 1.0.56-0 or newer, this source is registered as a plugin marketplace; set `COPILOT_COST_MARKETPLACE_NAME` / `--marketplace-name` and `COPILOT_COST_PLUGIN_NAME` / `--plugin-name` if your fork changes those marketplace identifiers. Set `COPILOT_COST_INSTALL_BASE_URL` or pass `--install-base-url \u003curl\u003e` when running installer scripts from an alternate raw-content location. Set `COPILOT_HOME` or pass `--copilot-home \u003cpath\u003e` to isolate installer writes.\n\nIf `/cost` is not available in an active Copilot CLI session after installing, run `/extensions` and enable `copilot-cli-cost` under **User**.\n\nWhen you run `copilot` inside this repository, Copilot CLI's extension resolver prefers the repo-local `.github/extensions/copilot-cli-cost` extension over the user-installed extension. The user-scoped shim intentionally stays pointed at the installed plugin copy for sessions outside the repository.\n\n### Manual install\n\nThe scripts perform these steps. To do them manually, first install the plugin:\n\n```shell\ncopilot plugin marketplace add DamianEdwards/copilot-cli-cost # if not already registered\ncopilot plugin install copilot-cli-cost@copilot-cli-cost-marketplace\n```\n\nThen run the extension shim installer from the installed plugin.\n\nPowerShell terminal:\n\n```powershell\n$installer = Get-ChildItem \"$env:USERPROFILE\\.copilot\\installed-plugins\" -Directory -Recurse |\n  Where-Object { Test-Path (Join-Path $_.FullName \"scripts\\install-extension-shim.mjs\") } |\n  Select-Object -First 1 -ExpandProperty FullName\n\nif (-not $installer) {\n  throw \"Could not find installed copilot-cli-cost plugin.\"\n}\n\nnode (Join-Path $installer \"scripts\\install-extension-shim.mjs\")\n```\n\nBash terminal:\n\n```bash\ninstaller=\"$(find \"$HOME/.copilot/installed-plugins\" -type f -path '*/scripts/install-extension-shim.mjs' | head -n 1)\"\nif [ -z \"$installer\" ]; then\n  echo \"Could not find installed copilot-cli-cost plugin.\" \u003e\u00262\n  exit 1\nfi\nnode \"$installer\"\n```\n\nConfigure `~/.copilot/settings.json`. Do not put `statusLine` in `config.json`; that file is managed by Copilot CLI and user settings may be moved or removed during startup. Use your machine's statusline launcher path:\n\n```jsonc\n{\n  \"experimental\": true,\n  \"experimental_flags\": [\"EXTENSIONS\", \"STATUS_LINE\"],\n  \"statusLine\": {\n    \"type\": \"command\",\n    \"command\": \"C:\\\\Users\\\\alex\\\\.copilot\\\\copilot-cli-cost\\\\statusline.cmd\"\n  },\n  \"footer\": {\n    \"showCustom\": true\n  }\n}\n```\n\nmacOS/Linux:\n\n```jsonc\n{\n  \"experimental\": true,\n  \"experimental_flags\": [\"EXTENSIONS\", \"STATUS_LINE\"],\n  \"statusLine\": {\n    \"type\": \"command\",\n    \"command\": \"sh \\\"/Users/alex/.copilot/copilot-cli-cost/statusline.sh\\\"\"\n  },\n  \"footer\": {\n    \"showCustom\": true\n  }\n}\n```\n\nThe statusline bridge prints a compact segment:\n\n```text\n💸 Cost ~$0.3059 (30.6 cr, 2% pro) · last 42K in/3K out\n```\n\nWhen the SDK extension can detect your current Copilot subscription, the statusline uses that cached plan for allowance percentages. `COPILOT_COST_PLAN` can still override the plan explicitly. If neither is available, the statusline falls back to `assumed pro` so the percentage is not presented as a detected plan.\n\nThe generated statusline launcher is workspace-aware because statusline settings point at a fixed command and do not use the extension resolver. When Copilot sends a statusline payload with `workspace.current_dir` or `cwd` inside a `copilot-cli-cost` checkout or worktree, the launcher runs that checkout's `src/cli/statusline.js`; otherwise it falls back to the installed plugin copy. Set `COPILOT_COST_STATUSLINE_DISABLE_WORKSPACE=true` to always use the installed copy.\n\n## Use\n\n```text\n/cost\n/cost help\n/cost version\n/cost update\n/cost panel on\n/cost panel off\n/cost panel refresh\n/cost session \u003csession-id\u003e\n/cost live-session \u003csession-id\u003e\n/cost --plan pro|pro-plus|max|business|enterprise\n/cost --currency USD|EUR|GBP|CAD|AUD|JPY|CHF\n```\n\n`/cost` is handled by extension JavaScript. It does not ask the model to calculate the result.\n\nUse `/cost update` to force the extension to re-detect your current Copilot subscription and rewrite the shared cache used by the statusline. If the host exposes a statusline refresh hook, the command also requests an immediate refresh; otherwise the updated plan appears on the next normal statusline refresh.\n\nThe panel opens a native window:\n\n```text\n/cost panel on\n```\n\nThe panel shows:\n\n- Usage-based estimate\n- Percentage of the selected plan's allowance used by the session\n- Searchable session picker for current, cached live, and completed sessions\n- Selected session ID and data source\n- Current or assumed subscription\n- Loaded extension version\n- What-if subscription selector\n- Display currency selector\n- Per-model token bucket breakdown\n- Collapsed raw JSON payload\n\n## Data sources\n\nThe SDK extension reads active-session metrics from Copilot CLI's session RPC API:\n\n```js\nawait session.rpc.usage.getMetrics()\n```\n\nThat response includes:\n\n- Per-model request counts\n- Copilot-reported AI credit usage (`totalNanoAiu`) when available\n- Input, cached input, cache write, output, and reasoning token buckets\n- Active model\n- Last-call input/output token counts\n- API duration\n- Code-change counters\n\nThe extension normalizes each read and writes a live snapshot to the platform cache folder:\n\n```text\nWindows: %LOCALAPPDATA%\\copilot-cli-cost\\live-sessions\nmacOS:   ~/Library/Caches/copilot-cli-cost/live-sessions\nLinux:   ${XDG_CACHE_HOME:-~/.cache}/copilot-cli-cost/live-sessions\n```\n\nCompleted local sessions can be read from:\n\n```text\nWindows: %USERPROFILE%\\.copilot\\session-state\\\u003csession-id\u003e\\events.jsonl\nmacOS/Linux: ~/.copilot/session-state/\u003csession-id\u003e/events.jsonl\n```\n\nThe parser reads the latest metrics event and extracts Copilot-reported AI credit usage and per-model token buckets.\n\nFor usage-based billing, Copilot-reported AI credits are preferred because they match the CLI's own **AI Credits** counter. Token-rate estimates are retained as a fallback when Copilot does not provide AI credit totals, and the panel labels which method was used.\n\nWhen statusline payloads include `transcript_path`, live snapshots are also grouped into a logical session. This keeps each resumed Copilot CLI instance as its own snapshot while letting `/cost`, the statusline segment, and the panel show the total cost across resumed instances.\n\n## Statusline passthrough\n\nSet `COPILOT_COST_STATUSLINE_PASSTHROUGH` to call another statusline command. The default passthrough mode enriches the stdin JSON with `copilot_cost` and lets the inner statusline render all output.\n\nPowerShell:\n\n```powershell\n$env:COPILOT_COST_STATUSLINE_PASSTHROUGH = \"C:\\Users\\alex\\.copilot\\statusline\\statusline.cmd\"\ncopilot\n```\n\nmacOS/Linux:\n\n```sh\nexport COPILOT_COST_STATUSLINE_PASSTHROUGH=\"$HOME/.copilot/statusline/statusline.sh\"\ncopilot\n```\n\nThe enriched payload includes:\n\n```jsonc\n{\n  \"copilot_cost\": {\n    \"schema_version\": 2,\n    \"status_line\": \"💸 Cost ~$0.3059 (30.6 cr, 2% pro) · last 42K in/3K out\",\n    \"aggregate_usage_based\": {\n      \"billingModel\": \"usage-based\",\n      \"totalUsd\": 0.305869,\n      \"aiCredits\": 30.5869,\n      \"creditCalculationSource\": \"copilot-cli-session-aiu\"\n    },\n    \"usage_based\": {\n      \"billingModel\": \"usage-based\",\n      \"totalUsd\": 0.305869,\n      \"aiCredits\": 30.5869,\n      \"creditCalculationSource\": \"copilot-cli-session-aiu\"\n    }\n  }\n}\n```\n\nSet decorate mode to combine this bridge's output with the passthrough output:\n\nPowerShell:\n\n```powershell\n$env:COPILOT_COST_STATUSLINE_MODE = \"decorate\"\n$env:COPILOT_COST_STATUSLINE_POSITION = \"right\"\ncopilot\n```\n\nmacOS/Linux:\n\n```sh\nexport COPILOT_COST_STATUSLINE_MODE=decorate\nexport COPILOT_COST_STATUSLINE_POSITION=right\ncopilot\n```\n\nStatusline environment variables:\n\n| Variable | Default | Meaning |\n| --- | --- | --- |\n| `COPILOT_COST_STATUSLINE_PASSTHROUGH` | unset | Command to invoke with enriched statusline JSON on stdin. |\n| `COPILOT_COST_STATUSLINE_MODE` | `passthrough` when passthrough is set, otherwise `standalone` | `passthrough`, `decorate`, or `standalone`. |\n| `COPILOT_COST_STATUSLINE_POSITION` | `right` | In `decorate` mode: `right`, `left`, `replace`, or `passthrough`. |\n| `COPILOT_COST_STATUSLINE_SEPARATOR` | ` · ` | In `decorate` mode: text between the passthrough output and cost segment. |\n| `COPILOT_COST_STATUSLINE_PASSTHROUGH_TIMEOUT_MS` | `1000` | Maximum time to wait for the passthrough command. |\n| `COPILOT_COST_STATUSLINE_HIDE_COST` | `false` | Cache live data but do not print the cost segment. |\n| `COPILOT_COST_STATUSLINE_COLOR` | `true` | Set to `false` to disable ANSI color in the rendered cost segment. |\n\n## Configuration\n\nSet these environment variables before launching `copilot`:\n\nPowerShell:\n\n```powershell\n$env:COPILOT_COST_PLAN = \"enterprise\"\n$env:COPILOT_COST_CURRENCY = \"EUR\"\ncopilot\n```\n\nmacOS/Linux:\n\n```sh\nexport COPILOT_COST_PLAN=enterprise\nexport COPILOT_COST_CURRENCY=EUR\ncopilot\n```\n\n| Variable | Meaning |\n| --- | --- |\n| `COPILOT_COST_PLAN` | Default plan when subscription detection is unavailable. |\n| `COPILOT_COST_CURRENCY` | Display currency code. USD is canonical. Non-USD values use Frankfurter unless an override is configured. |\n| `COPILOT_COST_EXCHANGE_RATE` | USD-to-display-currency exchange rate override for `COPILOT_COST_CURRENCY`. |\n| `COPILOT_COST_FX_\u003cCODE\u003e` | USD-to-currency exchange rate override for a specific currency, for example `COPILOT_COST_FX_EUR=0.9`. |\n| `COPILOT_COST_FX_CACHE` | Exchange-rate cache folder. Defaults to `%LOCALAPPDATA%\\copilot-cli-cost\\fx-rates` on Windows, `~/Library/Caches/copilot-cli-cost/fx-rates` on macOS, or `${XDG_CACHE_HOME:-~/.cache}/copilot-cli-cost/fx-rates` on Linux. |\n| `COPILOT_COST_SUBSCRIPTION_CACHE` | Current subscription cache file used by the statusline. Defaults to `current-subscription.json` under the platform cache root. |\n| `COPILOT_COST_PROMOTIONAL_ALLOWANCE` | Override promotional Business/Enterprise AI Credit allowances. During the June 1-September 1, 2026 transition this defaults on; set `false` to disable or `true` to force on. |\n| `COPILOT_COST_BILL_REASONING_TOKENS` | Set to `true` to include reasoning tokens as output-priced cost. By default they are shown as informational only. |\n\nThe live session cache can be overridden with `COPILOT_COST_LIVE_STORE`. By default it uses the same platform cache root as `COPILOT_COST_FX_CACHE`.\n\n### Native panel notes\n\nThe `/cost` command and calculator are pure Node.js. The native panel uses `@webviewjs/webview`, which installs a platform-specific optional package for Windows, macOS, and Linux x64. The extension bootstrap runs `npm install --include=optional --no-audit --no-fund` when those panel dependencies are missing.\n\nOn Linux, the native webview package still depends on system GTK/WebKit libraries supplied by your distribution, such as WebKitGTK and GTK. If `/cost panel on` fails to open, install your distribution's WebKitGTK/GTK runtime packages and reload the extension.\n\n## Standalone calculator\n\nClone the repository when you want to run tests or use the calculator directly:\n\n```powershell\ngit clone https://github.com/DamianEdwards/copilot-cli-cost.git\ncd copilot-cli-cost\nnpm test\n```\n\nExamples:\n\n```powershell\nnpm run cost -- --sample\nnpm run cost -- --session \u003csession-id\u003e --plan pro\nnpm run cost -- --live --plan max\nnpm run cost -- --sample --currency EUR\nnpm run cost -- --sample --currency EUR --exchange-rate 0.9\n```\n\nUsage JSON shape:\n\n```json\n{\n  \"sessionId\": \"sample-session-001\",\n  \"plan\": \"pro\",\n  \"currency\": \"USD\",\n  \"modelUsage\": [\n    {\n      \"model\": \"gpt-5.5\",\n      \"requests\": 3,\n      \"inputTokens\": 600000,\n      \"cachedInputTokens\": 420000,\n      \"cacheWriteTokens\": 0,\n      \"outputTokens\": 36000,\n      \"reasoningTokens\": 1200\n    }\n  ]\n}\n```\n\n## How estimates are calculated\n\nUsage-based billing uses published per-1M-token rates. `inputTokens` is the total input token count from Copilot metrics, and `cachedInputTokens` is the cached subset, so only uncached input tokens use the regular input rate:\n\n```text\nuncachedInputTokens = max(inputTokens - cachedInputTokens, 0)\ninputUsd            = uncachedInputTokens / 1,000,000 * inputPerMillionUsd\ncachedInputUsd      = cachedInputTokens   / 1,000,000 * cachedInputPerMillionUsd\ncacheWriteUsd       = cacheWriteTokens    / 1,000,000 * cacheWritePerMillionUsd\noutputUsd           = outputTokens        / 1,000,000 * outputPerMillionUsd\nreasoningUsd        = 0 unless COPILOT_COST_BILL_REASONING_TOKENS=true\naiCredits           = totalUsd / 0.01\nincludedAiCredits   = baseAiCredits + current flexAiCredits + current promotionalAiCredits\n```\n\nFor individual usage-based billing, Pro and Pro+ include a fixed base credit amount plus a variable flex allotment. The calculator reports the current published total as included credits and preserves the base/flex split in machine-readable output.\n\nDuring GitHub's June 1-September 1, 2026 usage-based billing transition, existing Copilot Business and Enterprise customers receive promotional included credits. The calculator applies those promotional credits by default during that window and preserves them as a separate `promotionalAiCredits` component, for example `7,000 included (3,900 base + 3,100 promotional)` for Copilot Enterprise.\n\nNon-USD currency values are display estimates. USD remains canonical because GitHub model rates and AI Credits are documented in USD. Non-USD `/cost` and panel requests fetch USD exchange rates from [Frankfurter](https://www.frankfurter.dev/) and cache them for reuse; explicit environment or CLI exchange-rate overrides take precedence.\n\n## Limitations\n\n- Rate tables are hardcoded in `src/core/rates.js` and should be checked against GitHub billing docs.\n- Reasoning tokens are shown as informational only unless `COPILOT_COST_BILL_REASONING_TOKENS=true`, because GitHub's published Copilot pricing table does not list a separate reasoning-token bucket.\n- Business and Enterprise included credits are pooled at the billing entity level, so a session estimate is not always incremental billable spend.\n- Taxes, regional billing rules, and GitHub billing-account currency handling are not modeled.\n- Statusline per-model attribution depends on successive cumulative payloads and the active model at each refresh. Resumed-session aggregation depends on `transcript_path`; without it, live snapshots fall back to the current `session_id` and cannot be linked to previous instances.\n\n## License\n\nMIT. See [LICENSE](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdamianedwards%2Fcopilot-cli-cost","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdamianedwards%2Fcopilot-cli-cost","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdamianedwards%2Fcopilot-cli-cost/lists"}