# Repo Metrics

> GitHub repo metrics for your-org/your-repo. Tracks total stars, stars added, weekly contributors (unique humans across issues/PRs/comments), new and active PRs, new and active issues, unique visitors, unique clones, and pageviews. Stores traffic + star snapshots to CSV for historical tracking. Use when the user asks for "repo metrics", "GitHub stats", "OSS metrics", "how's the repo doing", or wants contributor/traffic numbers.

- Skill: `warpdotdev/repo-metrics` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add warpdotdev/repo-metrics`
- Raw SKILL.md: https://api.skillmd.com/api/skills/warpdotdev/repo-metrics/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Data & Analytics
- Author: warpdotdev (https://skillmd.com/u/warpdotdev)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/warpdotdev/repo-metrics

---


# Repo Metrics

Fetch weekly GitHub metrics for `your-org/your-repo` and display a week-over-week summary. Traffic and star counts are persisted to CSV since the GitHub traffic API only retains 14 days.

## Metrics tracked

1. **Total stars** — current stargazer count
2. **Stars added** — delta from previous snapshot (requires running weekly to build history)
3. **Contributors per week** — unique humans who opened an issue, opened a PR, or commented on an issue/PR. Bots excluded.
4. **New PRs per week** — PRs created in the week
5. **Active PRs per week** — PRs updated in the week
6. **New issues per week** — issues created in the week
7. **Active issues per week** — issues updated in the week (capped at 1,000 by search API)
8. **Unique visitors per week** — from traffic API
9. **Unique clones per week** — from traffic API
10. **Pageviews per week** — from traffic API

## Prerequisites

Auth priority (first match wins):
1. `GITHUB_TOKEN_FOR_REPO_STATS_IN_BUZZ` env var — a repo-scoped token, used in cloud runs
2. `GITHUB_TOKEN` env var — generic fallback
3. `gh` CLI — auto-detected locally if authenticated (`gh auth status`). No PAT needed.

For traffic endpoints (views, clones), the token or `gh` account needs push access to the repo.

The scripts use only the Python standard library — run them with your system
`python3` (no virtualenv or extra packages needed).

## Parameters

- **Period** — number of days to look back. Default: 14 (two Mon–Sun weeks). Override via user request.
- **Repo** — defaults to `your-org/your-repo`.

## Workflow

### Step 1: Fetch metrics

```bash
python3 .agents/skills/repo-metrics/scripts/fetch_metrics.py --days 14 > /tmp/repo_metrics.json
```

The script:
- Fetches repo metadata (star count)
- Fetches daily traffic (views, clones) and groups into Mon–Sun weeks
- Runs per-week search queries for: new PRs, active PRs, new issues, active issues
- Fetches issue/PR comments and counts unique human authors per week (= contributors)
- Outputs structured JSON with a `weeks` array containing all metrics per week

### Step 2: Store history

```bash
python3 .agents/skills/repo-metrics/scripts/store_traffic.py /tmp/repo_metrics.json
```

Appends to CSVs in `reports/github-traffic/`:
- `daily_traffic.csv` — daily views/clones, deduped by date
- `stars.csv` — snapshot date + star count (for computing “stars added” week-over-week)

### Step 3: Present results

Format a week-over-week summary:

```
📊 your-org/your-repo — Weekly Metrics

                         Apr 21–27    Apr 28–May 3
Total stars              10,000          12,500
Stars added                   —           2,500
Contributors/week            50             120
New PRs/week                  8              40
Active PRs/week              12              45
New issues/week              15              35
Active issues/week          110             140
Unique visitors/week      4,000          20,000
Unique clones/week          100             400
Pageviews/week            8,000          40,000
```

### Step 4: Validate

- If traffic returns 403, flag that the token lacks push access
- If search returns >1,000 results, note the count is capped
- Star count should match what's shown on the repo page
- “Stars added” requires a prior snapshot — will be blank on first run

## Important notes

- **Traffic data only covers 14 days** — run at least every 14 days to avoid gaps.
- **Stars added requires historical snapshots** — the API doesn’t provide per-day star counts for repos >40K stars. The store script records the current count each run; the delta gives “stars added”.
- **Search API caps at 1,000 results** per query. “Active issues” may hit this.
- **Contributors = unique humans** who opened issues, PRs, or commented. Bots excluded by checking `user.type == "Bot"` or login ending in `[bot]`.
- **Weeks are Mon–Sun**, matching GitHub’s convention.
- **Do NOT log or hardcode tokens** — use env vars.