GitHub Traffic Vault

GitHub only retains repository traffic data (views, clones, top referrers, top paths) for about 14 days. GitHub Traffic Vault permanently archives that data in SQLite for all of your public repos, so nothing ever gets lost.

All your repos at a glance	Per-repo history and status	Pick any time window

What it does

• Archives traffic forever: views, clones, top referrers, top paths — the stuff GitHub only keeps for ~14 days. Stored locally in SQLite, under your control
• Syncs your public repos: discovers everything you own, pulls fresh numbers, and remembers the history. Hit Sync Now in the browser or schedule sync from the terminal
• Shows the big picture: an index page with every repo as a card — totals for the period you pick, plus today. Defaults to the last 30 days
• Drills into one repo: daily chart, month-by-month breakdown, and a quick status glance (CI, latest release, open PRs)
• Flexible date ranges: same picker on index and detail — this month, last month, last N months, all time, or a custom from/to range

You need a GitHub personal access token with repo scope.

Option A — .env file (works everywhere). Copy .env.example to .env and set GITHUB_TOKEN.

Option B — GitHub CLI (Mac/Linux shortcut). If gh auth login already worked for you, leave .env empty and the app will borrow that token.

Requires Python 3.12 and Poetry.

poetry install
poetry run github-traffic-vault sync

CLI

github-traffic-vault sync                          # discover + sync (cron entry point)
github-traffic-vault sync --only owner/repo        # restrict to specific repos
github-traffic-vault sync --dry-run                # hit the API, roll back DB

github-traffic-vault repos                         # list known repos
github-traffic-vault show <repo> [--since DATE]    # daily table + latest top lists

github-traffic-vault export <repo|all> [--format csv|json] [--kind views|clones|referrers|paths]
github-traffic-vault top [--by views|clones] [--since DATE] [--limit N]

github-traffic-vault serve [--host 127.0.0.1] [--port 8800] [--reload]

Web UI

poetry run github-traffic-vault serve
# open http://127.0.0.1:8800

The SPA, server-rendered (FastAPI + Jinja2). Each repo gets a card showing 14-day totals and a per-day breakdown grouped by month. The Sync Now button kicks off a real sync (blocks ~7s, then re-renders). The same data is available as JSON at /api/repos.json.

With --reload, you enable uvicorn auto-reload for dev (or run via Docker with hot-reload, see below).

Docker

A Dockerfile and a compose file for local dev with hot-reload.

Mac dev (hot-reload)

cp .env.example .env
# set GITHUB_TOKEN, or leave empty to use gh auth token inside the container

docker compose up --build

UI at http://127.0.0.1:8800. Source is bind-mounted with hot-reload, so edits to the code show up without rebuilding.

Sync manually from another terminal:

docker compose exec github-traffic-vault github-traffic-vault sync

Terminal commands

The web UI covers most of what I need. If you prefer the command line:

Command	What it does
github-traffic-vault sync	Discover repos and pull traffic data
github-traffic-vault repos	List what's in the vault
github-traffic-vault show <owner/repo>	Daily table for one repo
github-traffic-vault export	Dump one repo or everything as CSV or JSON
github-traffic-vault top	Rank repos by views or clones
github-traffic-vault serve	Start the web UI

Run github-traffic-vault --help for flags (--since, --only, --dry-run, etc.).

Where the data lives

Everything lands in a data/ folder next to where you run the app:

data/
├── github-traffic-vault.db
└── github-traffic-vault.log

Back up github-traffic-vault.db and you're good. Open it with any SQLite client if you're curious.

A few honest limits

• One GitHub account, public repos only
• The web UI listens on 127.0.0.1 with no login. Fine for local use
• No test suite yet as it's a personal tool that still grows its legs

License

MIT, see LICENSE.