{"id":51238588,"url":"https://github.com/trsdn/copilot-usage-report","last_synced_at":"2026-06-28T22:30:21.269Z","repository":{"id":366764342,"uuid":"1277735123","full_name":"trsdn/copilot-usage-report","owner":"trsdn","description":"A GitHub Copilot CLI skill: local token \u0026 cost usage report per model (AI Units / credits / USD).","archived":false,"fork":false,"pushed_at":"2026-06-23T07:22:41.000Z","size":264,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-23T09:04:29.247Z","etag":null,"topics":["ai-units","cli","copilot","copilot-cli","cost-tracking","finops","github-copilot","observability","python","skill","token-usage","usage-report"],"latest_commit_sha":null,"homepage":null,"language":"Python","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/trsdn.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-06-23T06:31:41.000Z","updated_at":"2026-06-23T07:22:45.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/trsdn/copilot-usage-report","commit_stats":null,"previous_names":["trsdn/copilot-usage-report"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/trsdn/copilot-usage-report","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/trsdn%2Fcopilot-usage-report","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/trsdn%2Fcopilot-usage-report/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/trsdn%2Fcopilot-usage-report/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/trsdn%2Fcopilot-usage-report/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/trsdn","download_url":"https://codeload.github.com/trsdn/copilot-usage-report/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/trsdn%2Fcopilot-usage-report/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34906700,"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-28T02:00:05.809Z","response_time":54,"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":["ai-units","cli","copilot","copilot-cli","cost-tracking","finops","github-copilot","observability","python","skill","token-usage","usage-report"],"created_at":"2026-06-28T22:30:20.789Z","updated_at":"2026-06-28T22:30:21.260Z","avatar_url":"https://github.com/trsdn.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# copilot-usage-report\n\n[![CI](https://github.com/trsdn/copilot-usage-report/actions/workflows/ci.yml/badge.svg)](https://github.com/trsdn/copilot-usage-report/actions/workflows/ci.yml)\n[![License: MIT](https://img.shields.io/badge/License-MIT-22c55e.svg?style=flat-square)](LICENSE)\n[![Python 3.8+](https://img.shields.io/badge/Python-3.8%2B-3776AB.svg?style=flat-square\u0026logo=python\u0026logoColor=white)](https://www.python.org/)\n![Dependencies: none](https://img.shields.io/badge/dependencies-none-22c55e.svg?style=flat-square)\n![Platform: macOS | Linux](https://img.shields.io/badge/platform-macOS%20%7C%20Linux-555.svg?style=flat-square)\n[![Copilot CLI skill](https://img.shields.io/badge/Copilot%20CLI-skill-000.svg?style=flat-square\u0026logo=githubcopilot\u0026logoColor=white)](https://docs.github.com/copilot/concepts/agents/about-copilot-cli)\n![Output: Markdown · JSON · HTML](https://img.shields.io/badge/output-Markdown%20%C2%B7%20JSON%20%C2%B7%20HTML-7c3aed.svg?style=flat-square)\n\nA [GitHub Copilot CLI](https://docs.github.com/copilot/concepts/agents/about-copilot-cli)\n**skill** that generates a token-and-cost usage report from your local Copilot CLI\ntelemetry, broken down per model and converted to **GitHub AI Units / AI Credits / USD**.\n\nAsk the agent something like *\"how many tokens / AI credits did I use in the last 48h?\"*\nand it runs the bundled parser and presents a markdown table. The script also works as a\nplain standalone CLI and can emit **JSON** or a **self-contained HTML report** (`--html`).\n\n\u003e **Privacy:** everything runs locally against `~/.copilot/logs/`. No data leaves your\n\u003e machine, nothing is uploaded.\n\n## HTML report (`--html`)\n\nA self-contained, offline report — summary cards plus a per-model table with spend bars\n(dark-mode aware, inline CSS, no external assets):\n\n![Sample HTML usage report](docs/sample-report.png)\n\n\u003e Sample shown with synthetic data. Generate your own with\n\u003e `… --html --out usage.html` (see [Standalone CLI usage](#standalone-cli-usage)).\n\n## Example (markdown, default)\n\n```bash\npython3 copilot-usage-report/scripts/usage_report.py 24h\n```\n\n```\n# Copilot CLI usage report\n\n**Window (UTC):** 2026-06-22 06:30 → 2026-06-23 06:30\n**Basis:** 1 AI Unit = 1 GitHub AI credit = $0.01 USD (from telemetry `total_nano_aiu`).\n\n| Model | Calls | Input | Cache-read | Cache-write | Output | Reasoning | AI Units | USD |\n|---|--:|--:|--:|--:|--:|--:|--:|--:|\n| claude-opus-4.8 | 1490 | 156,914,754 | 146,333,432 | 10,510,108 | 1,362,434 | 123,729 | 17,327.18 | $173.27 |\n| ... | | | | | | | | |\n| **TOTAL** | **2597** | **242,246,546** | ... | | | | **22,609.50** | **$226.09** |\n\n- **Total cost: 22,609.50 AI Units = $226.09**\n- Cache-read share of input: **93.5%**\n- Top model: **claude-opus-4.8** at $173.27 (77% of spend)\n```\n\n## Install as a Copilot CLI skill\n\nCopilot CLI discovers skills under `.copilot/skills/` (per-project) or\n`~/.copilot/skills/` (global). Drop the `copilot-usage-report/` folder into either:\n\n```bash\n# global, available in every session\ngit clone https://github.com/trsdn/copilot-usage-report.git\nmkdir -p ~/.copilot/skills\ncp -r copilot-usage-report/copilot-usage-report ~/.copilot/skills/\n\n# …or per-project\ncp -r copilot-usage-report/copilot-usage-report \u003cyour-repo\u003e/.copilot/skills/\n```\n\nThe skill is then auto-loaded; just ask the agent for a usage report.\n\n## Standalone CLI usage\n\nRequires **Python 3** (standard library only — no dependencies).\n\n```bash\npython3 copilot-usage-report/scripts/usage_report.py \u003cTIMEFRAME\u003e\n```\n\n`\u003cTIMEFRAME\u003e` accepts:\n\n| Form | Meaning |\n|---|---|\n| `30m`, `12h`, `48h`, `7d`, `2w` | relative window ending now (UTC); default `24h` |\n| `today`, `yesterday` | calendar day (UTC) |\n| `--from ISO --to ISO` | explicit window, e.g. `--from 2026-06-01T00:00:00 --to 2026-06-08T00:00:00` |\n\nOther flags:\n\n- `--json` — machine-readable output instead of the markdown table.\n- `--html` — a **self-contained, offline** HTML report (summary cards + per-model\n  table with spend bars; inline CSS, no external assets).\n- `--out FILE` — write the report to a file instead of stdout (works with any format).\n- `--logs DIR` — point at a different log directory (default `~/.copilot/logs`).\n\n```bash\npython3 copilot-usage-report/scripts/usage_report.py 7d\npython3 copilot-usage-report/scripts/usage_report.py today\npython3 copilot-usage-report/scripts/usage_report.py 7d --html --out usage.html\npython3 copilot-usage-report/scripts/usage_report.py --from 2026-06-01T00:00:00 --to 2026-06-08T00:00:00 --json\n```\n\n\u003e Log files can total **\u003e1 GB**; the parser streams them, so a run takes ~10–30 s.\n\n## How it works\n\nCopilot CLI writes `assistant_usage` telemetry events to `~/.copilot/logs/*.log`. Each\nevent carries `properties.model` and a `metrics` block. The report aggregates per model:\n\n- `input_tokens = input_tokens_uncached + cache_read_tokens + cache_write_tokens`\n- **AI Units (AIU)** `= total_nano_aiu / 1e9` — GitHub's own billed amount.\n- Billing basis (GitHub official): **1 AI Unit = 1 GitHub AI credit = $0.01 USD**, so\n  `USD = AIU / 100`. AIU is authoritative and stays correct even for models not in the\n  local rate card.\n- `cache_write` is a real, separately-billed operation for Anthropic models only; OpenAI\n  / Google rate cards have no cache-write charge.\n\nThe optional per-1M-token `RATES` table in the script is a **cross-check only** — AIU\nfrom telemetry is the source of truth. Update rates from the official page:\n\u003chttps://docs.github.com/en/copilot/reference/copilot-billing/models-and-pricing\u003e\n\n## Repo layout\n\n```\ncopilot-usage-report/\n├── README.md\n├── LICENSE\n├── .github/workflows/ci.yml    # smoke test on Python 3.8 / 3.10 / 3.12\n├── tests/\n│   └── smoke.py                # dependency-free markdown/JSON/HTML smoke test\n├── docs/\n│   ├── sample-report.html      # example HTML report (synthetic data)\n│   └── sample-report.png       # screenshot used in this README\n└── copilot-usage-report/       # the drop-in skill (copy into .copilot/skills/)\n    ├── SKILL.md                # skill manifest + agent instructions\n    └── scripts/\n        └── usage_report.py     # the parser / standalone CLI\n```\n\n## Contributing\n\nIssues and PRs welcome. The script is plain Python 3 standard library — no build, no\ndependencies. Run the smoke test before sending a PR:\n\n```bash\npython3 tests/smoke.py\n```\n\nWhen a new model appears, add its per-1M-token rates to `RATES` in\n`usage_report.py` from the\n[official pricing page](https://docs.github.com/en/copilot/reference/copilot-billing/models-and-pricing)\n(AIU from telemetry remains authoritative; the rate card is only a cross-check).\n\n## License\n\n[MIT](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftrsdn%2Fcopilot-usage-report","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftrsdn%2Fcopilot-usage-report","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftrsdn%2Fcopilot-usage-report/lists"}