gh-usage: A Tool for Analyzing GitHub Copilot Usage
Primary Purpose:
gh-usage is a fast Rust-based command-line tool designed to analyze local GitHub Copilot usage records from VS Code and the Copilot CLI. It provides detailed summaries of credit consumption and exports reports in CSV or JSON formats, enabling users to track and manage their Copilot usage effectively.
Key Features:
Fast Performance: Built using Rust, gh-usage efficiently scans large volumes of data quickly.
Cross-Platform Support: Compatible with Windows, Linux, and macOS, ensuring broad accessibility.
Export Flexibility: Exports detailed reports in CSV for spreadsheet analysis and HTML for interactive review, catering to different analytical needs.
Multi-Machine Aggregation: Combines CSV files from multiple devices into a single report, facilitating comprehensive usage comparisons across teams or devices.
Customizable Options: Offers command-line parameters for tailored data collection, such as including CLI logs or filtering by date range.
Offline Functionality: Operates without the need for internet access or server setup, ensuring ease of use and privacy.
Audience & Benefits:
Ideal for individuals and teams utilizing GitHub Copilot, gh-usage provides actionable insights into their usage patterns. Users can identify peak usage periods, understand which models contribute most to credit consumption, and compare usage across multiple devices. The tool also simplifies report sharing, enabling seamless communication of findings without additional setup requirements.
Installation:
gh-usage can be installed via winget on Windows, making it easy to integrate into your workflow.
This tool is a valuable resource for anyone looking to optimize their GitHub Copilot usage and gain clear insights into their credit consumption.
> One command turns your scattered local GitHub Copilot usage records into a clean, visual report.
> Nothing is uploaded, nothing phones home — your data stays on your machine.
🙋 Who it's for
Heavy Copilot users who want to see how many credits they spent this month, which days were busiest, and which model they rely on most.
Team leads and engineering managers who need a quick read on usage across people and projects for reviews and planning.
Anyone who reports on their work and wants a report they can screenshot and share, instead of raw logs.
✨ Highlights
⚡ Fast
Written in Rust, it scans local history directories quickly with a light footprint. In one local run, it processed 877 files and extracted 1,020 records in 1.52 seconds.
+- GitHub Copilot Usage ---------------------------------+
| records 1020 scanned files 877 |
| total credits 157204.3 candidate lines 102 |
| active days 21 parse errors 0 |
| avg / day 7485.9 total time 1.52 s |
+--------------------------------------------------------+
🔒 Local and private
Runs entirely on your machine. It only reads files that already exist locally — nothing is uploaded.
One-click privacy mask. A built-in toggle blurs hostnames, project names, and session titles, so screenshots are safe to share.
You own the data. Every result is written to a local file you choose — keep it or delete it, your call.
The report is a single self-contained HTML file — double-click to open it in any browser. No database, no server, no internet required. Clean dark theme, tidy layout, and built-in English/Chinese switching.
📊 What's in the report
Key metrics at a glance
Total credits, active days, record count, daily average, total AI interaction time, and average time per exchange — the numbers you care about, right at the top.
Trends and model breakdown
A daily bar chart shows which days were busiest, and a donut chart breaks down each model's share at a glance.
Drill down by project and session
A per-project bar chart lets you click to filter, and a "top sessions by credits" list shows exactly where your usage went.
A searchable, filterable records table
The records table supports keyword search, filtering by model and source, click-to-sort columns, and pagination. The screenshot below has privacy mode on — sensitive fields are masked automatically.
Sidebar filters
Filter by machine, project, or date range from the left, and the report updates live — no setup required.
One-click screenshot
The camera button in the top-right saves the entire page as a single image (a crisp JPEG, around 430 KB). Privacy masking turns on automatically while capturing, so it's safe to share.
🚀 Getting started
1. Install
Windows (via the Windows Package Manager):
winget install gh-usage
Upgrade:
winget upgrade gh-usage
Linux / macOS: download the archive for your platform from the Releases page, unpack it, and run gh-usage.
2. Run
Run it from your terminal:
gh-usage
It writes two files to the current directory:
copilot-usage-.csv — import into Excel for deeper analysis
copilot-usage-.html — the report you open with a double-click
3. Open the report
Double-click the HTML file. Search, filter, switch language, toggle privacy, and save a screenshot — all from the page.
Run gh-usage on each machine, collect the copilot-usage-*.csv files into one folder, then:
gh-usage --merge .\shared\copilot-usage
It reads every CSV, deduplicates records, and produces one combined report with a per-machine breakdown — handy for swapping machines, team reviews, or comparing your desktop against your laptop.
📄 CSV fields
Each row is one usage record. Common fields include machine name, local time, session title, source, model, credits spent, the raw credit details, and the source file and line number. The CSV includes a UTF-8 BOM by default so Windows Excel opens it cleanly (use --no-bom to turn it off).
⚠️ Good to know
gh-usage is built for local analysis and review — great for spotting trends and rough comparisons, but not a replacement for GitHub's official billing or usage reports.
It only reads files that exist locally; deleted history can't be recovered.
Records without credit details are skipped.
It uses your system's standard VS Code data directory by default, and supports custom paths.
📚 Options
--include-cli-logs Include GitHub Copilot CLI records
--since-days Only scan files modified within the last N days
--output Write CSV or JSON to a specific path
--html Write the HTML report to a specific path
--no-html Do not generate the HTML report
--merge [DIR] Merge existing copilot-usage-*.csv files into one report
--format csv|json Choose the output format
--hostname Override the machine name stored in records
Run gh-usage --help for the full command reference.
📜 License
Released under the MIT License — free to use, modify, and distribute.
🤝 Contributing
Issues and pull requests are welcome. If this tool helps you out, a ⭐ Star is always appreciated.
Generated locally by gh-usage · your data stays on your machine.
