Fetch and analyze GitHub repository traffic data — page views, git clones, referral sources, popular pages, and star growth. Optionally generate trend charts as PNG images.
Prerequisites:
gh CLI must be installed and authenticated
Push (write) access to the target repository is required — GitHub's Traffic API does not work with read-only access
matplotlib is optional (for PNG chart generation; falls back to ASCII if unavailable)
When to Use
The user asks about repository traffic, page views, clone counts, or where visitors come from
The user wants to see traffic trends over time (weekly, monthly, quarterly)
The user wants to generate traffic report charts for sharing or documentation
The user wants to periodically snapshot traffic data to build long-term history
Important: GitHub Traffic API Limitations
GitHub only provides the last 14 days of traffic data. To track trends over longer periods (30 days, 90 days, etc.), the script stores each fetch in a local history file (~/.github-traffic/<repo>_traffic.json).
To build meaningful 30/90-day charts, run the script at least every 14 days (daily is ideal). Gaps longer than 14 days will show as missing data in charts.
Permissions
The GitHub Traffic API requires push access to the repository. This means:
Repository owners and admins: full access
Collaborators with write/maintain role: full access
Read-only users and forkers: no access (API returns 403)
If you get a permission error, check your gh auth status and ensure your token has the repo scope.
Troubleshooting
Problem
Solution
"Must have push access" error
You need write access to the repo. Check gh auth status.
Chart shows only 14 days
GitHub only provides 14-day windows. Run --snapshot regularly to accumulate history.
matplotlib not found
Install with pip install matplotlib. Or use --ascii for text-based charts.
No data for some dates
GitHub may not report days with zero traffic. These gaps are normal.
