Skip to content

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 ​

sh
npm install -g ghusage
ghusage --version

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

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

sh
npm install -g ghusage@latest

If 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 example ghusage: fetching @ghusage/[email protected] ....

  • It keeps only the binary, in a per-user cache, and uses that copy from then on:

    OSCache directory
    macOS~/Library/Caches/ghusage
    Linux$XDG_CACHE_HOME/ghusage, or ~/.cache/ghusage
    Windows%LOCALAPPDATA%\ghusage\cache

    Binaries are stored under native/<version>/<platform>/ there. Set GHUSAGE_CACHE_DIR to use another directory. Deleting the directory is safe; it is filled again when needed.

  • Set GHUSAGE_NO_AUTO_INSTALL=1 to turn this off. ghusage then exits with an explanation instead.

Other notes:

  • On platforms not listed above the launcher exits with a message; build from source instead.
  • Set GHUSAGE_BINARY to the path of a ghusage binary 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=optional or --no-optional).
  • A minimum release age setting (npm --before, --min-release-age, mise minimum_release_age) held the platform package back.
  • GHUSAGE_NO_AUTO_INSTALL is set, so the launcher did not try to fetch it.

To fix it:

  1. Reinstall the same version, so npm installs the platform package (replace 0.1.1 with the version from the message):

    sh
    npm uninstall -g ghusage && npm install -g [email protected]
  2. Check which registry npm uses:

    sh
    npm config get registry

    If 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 of ghusage meanwhile (npm view ghusage versions lists them):

    sh
    npm install -g ghusage@<previous version>
  3. You can also install from the public npm registry directly:

    sh
    npm install -g [email protected] --registry https://registry.npmjs.org

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

sh
cargo install --git https://github.com/tanahiro2010/ghusage

Or build a local checkout:

sh
git clone https://github.com/tanahiro2010/ghusage
cd ghusage
cargo build --release
./target/release/ghusage --version

Platforms

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.

sh
ghusage auth status
text
Logged 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/5000

First sync ​

sh
ghusage sync

By default sync fetches the last 30 days (today and the 29 days before it). Use --since for a longer range:

sh
ghusage sync --since 2026-01-01

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

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

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

text
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:00

Choosing a period ​

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

A date given to --until includes that whole day. See Periods and time zones.

Filtering ​

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

Filters only affect reports; sync always fetches everything for the period.

Scripts and exports ​

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

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