Getting started
ghusage analyzes a developer's GitHub activity: commits, pull requests, reviews, comments, issues, and the activity inside pull requests. It fetches data from the GitHub API into a local SQLite cache and builds reports from that cache.
Install
npm
npm install -g ghusage
ghusage --versionThe ghusage npm package is a small Node.js launcher. A prebuilt native binary for your platform is installed as an optional dependency, and the launcher runs it with your arguments. Node.js 18 or newer is required.
| Platform | npm package |
|---|---|
| macOS, Apple Silicon | @ghusage/ghusage-darwin-arm64 |
| macOS, Intel | @ghusage/ghusage-darwin-x64 |
| Linux x64 (statically linked) | @ghusage/ghusage-linux-x64 |
| Linux arm64 (statically linked) | @ghusage/ghusage-linux-arm64 |
| Windows x64 | @ghusage/ghusage-win32-x64 |
| Windows arm64 | @ghusage/ghusage-win32-arm64 |
You only install ghusage; npm picks the matching package above automatically.
To update to the latest release:
npm install -g ghusage@latestIf npm did not install the platform package (see Missing native package for why this happens), the launcher fetches it the first time you run ghusage:
It runs
npm pack @ghusage/ghusage-<platform>@<version>, so your npm configuration applies as usual: the registry or registry proxy you use, authentication, and npm's integrity checks. It prints one line to stderr while doing so, for exampleghusage: fetching @ghusage/[email protected] ....It keeps only the binary, in a per-user cache, and uses that copy from then on:
OS Cache directory macOS ~/Library/Caches/ghusageLinux $XDG_CACHE_HOME/ghusage, or~/.cache/ghusageWindows %LOCALAPPDATA%\ghusage\cacheBinaries are stored under
native/<version>/<platform>/there. SetGHUSAGE_CACHE_DIRto use another directory. Deleting the directory is safe; it is filled again when needed.Set
GHUSAGE_NO_AUTO_INSTALL=1to turn this off.ghusagethen exits with an explanation instead.
Other notes:
- On platforms not listed above the launcher exits with a message; build from source instead.
- Set
GHUSAGE_BINARYto the path of aghusagebinary to make the launcher run that binary instead (for example one you built yourself). It takes precedence over the installed and the cached binary.
Missing native package
If ghusage exits with the native binary for <platform> is missing, npm installed the launcher but not the platform package of the same version, and fetching it automatically did not work either. Common causes:
- The release was published moments ago and your registry does not serve the platform package yet.
- Your npm registry is a proxy, mirror or security tool that holds new versions back, so it serves the new launcher but not yet the new platform package.
- Optional dependencies were skipped (
npm install --omit=optionalor--no-optional). - A minimum release age setting (
npm --before,--min-release-age, miseminimum_release_age) held the platform package back. GHUSAGE_NO_AUTO_INSTALLis set, so the launcher did not try to fetch it.
To fix it:
Reinstall the same version, so npm installs the platform package (replace
0.1.1with the version from the message):shnpm uninstall -g ghusage && npm install -g [email protected]Check which registry npm uses:
shnpm config get registryIf it is not
https://registry.npmjs.org/but a proxy or mirror, wait until it serves the new platform package, or install the previous version ofghusagemeanwhile (npm view ghusage versionslists them):shnpm install -g ghusage@<previous version>You can also install from the public npm registry directly:
shnpm install -g [email protected] --registry https://registry.npmjs.orgIf your organization requires its registry proxy, follow that policy instead.
From source
You need a Rust toolchain (Rust 1.89 or newer).
Install directly from the repository:
cargo install --git https://github.com/tanahiro2010/ghusageOr build a local checkout:
git clone https://github.com/tanahiro2010/ghusage
cd ghusage
cargo build --release
./target/release/ghusage --versionPlatforms
ghusage is developed and used on macOS (Apple Silicon). The code is written to be portable, and continuous integration is set up to build and test it on Linux (x86_64 and ARM64), macOS (ARM64 and Intel) and Windows, but Linux and Windows have not yet been verified by hand on real machines. Please report problems you find.
Authenticate
If you already use the GitHub CLI and are logged in, there is nothing to do: ghusage uses gh auth token. Otherwise set GH_TOKEN (or GITHUB_TOKEN) or pass --token-file. See Authentication.
ghusage auth statusLogged in as octocat (credentials from gh auth token)
token scopes: gist, read:org, repo
rate limit: core 4998/5000 (resets 2026-11-21T11:02:13+00:00), search 30/30, graphql 4990/5000First sync
ghusage syncBy default sync fetches the last 30 days (today and the 29 days before it). Use --since for a longer range:
ghusage sync --since 2026-01-01The first sync of a busy account can take a while; later syncs only fetch what is missing or changed. See Syncing and the cache.
You do not have to run sync first: report commands fetch missing ranges automatically. Running it explicitly lets you see progress and the result.
Reports
ghusage # overview of the last 7 days (default command)
ghusage overview --since 30d
ghusage daily --since 14d
ghusage weekly # last 8 weeks
ghusage monthly # last 6 calendar months
ghusage yearly # this year and the 2 before
ghusage repos
ghusage prs --details
ghusage reviews
ghusage comments
ghusage issues
ghusage pr https://github.com/OWNER/REPO/pull/123 --timelineEvery report ends with a coverage line. Coverage: complete means every data kind was fully fetched for the whole period. Anything else lists the ranges that are missing or partial:
Coverage: not_yet_synced (last sync: -)
commits: not_yet_synced — not_yet_synced 2026-11-01 00:00–2026-11-04 00:00
pull_requests: not_yet_synced — not_yet_synced 2026-11-01 00:00–2026-11-04 00:00
issues: not_yet_synced — not_yet_synced 2026-11-01 00:00–2026-11-04 00:00Choosing a period
ghusage overview --since 2026-11-01 --until 2026-11-30 # whole of November
ghusage daily --since 7d # today and the 6 days before
ghusage weekly --since 4w # this week and the 3 before
ghusage overview --since yesterday --until yesterday # just yesterday
ghusage daily --timezone America/New_YorkA date given to --until includes that whole day. See Periods and time zones.
Filtering
ghusage repos --owner my-org
ghusage prs --repo my-org/api --repo my-org/web
ghusage overview --visibility public
ghusage overview --ownership external # repositories you do not ownFilters only affect reports; sync always fetches everything for the period.
Scripts and exports
ghusage weekly --format json > weekly.json
ghusage prs --format csv > prs.csv
ghusage overview --format json --require-complete || echo "data incomplete"JSON and CSV hide private repository names and titles unless you pass --include-private. See JSON and CSV output.
Offline use
ghusage overview --offline--offline never contacts GitHub. Ranges that were never synced are shown as not_yet_synced, and a note is printed to stderr.
Next steps
- Read the metric definitions to know exactly what each number means.
- Read the known limitations before relying on the numbers.
- Try the terminal UI:
ghusage tui.