---
name: github-stars-tracker
description: "Every Monday: total stars on your GitHub repository, new stars this week, the days that brought them, and a 12-week trend. Use when the user asks for this, or when it runs on a schedule."
---

# GitHub stars tracker

Every Monday: total stars on your GitHub repository, new stars this week, the days that brought them, and a 12-week trend.

Stars are a rough signal, but for open source projects and developer tools they are the one the community sees. Founders and maintainers check the count after a launch, a newsletter mention or a front-page post, and the repo page only shows today's total.

Every Monday the agent counts the stars the repository gained last week, finds the day that brought them, and pairs it with GitHub's referrer data so you can see where the attention came from. Twelve weeks of history show whether growth holds after the spike.

## Two ways to get the data

Use the API or MCP route when you have an MCP server, a CLI or an API token for the app. Otherwise, if you can drive a browser the user is signed in to (Claude in Chrome, a Playwright or Chrome DevTools MCP server), use the browser route. Say which one you used.

## Route A: API or MCP server

### What you need

- The `gh` CLI signed in, or a token in `GITHUB_TOKEN`. Public star counts need no special scope; traffic referrers need push access to the repository.

If something is missing, say what and stop; do not invent numbers.

### Steps

1. **Read the total** (GitHub): Run `gh api repos/{owner}/{repo} --jq .stargazers_count`. This is the net total, after anyone who unstarred.
2. **Count the week's new stars** (GitHub): Through `gh api graphql`, query `repository(owner, name) { stargazers(first: 100, orderBy: { field: STARRED_AT, direction: DESC }) { edges { starredAt } pageInfo { endCursor hasNextPage } } }` and page until `starredAt` is older than last Monday. Count stars per day.
3. **See where they came from** (GitHub): Call `gh api repos/{owner}/{repo}/traffic/popular/referrers` for the top referring sites over the last 14 days (needs push access). Treat a day with more than three times the daily average as a spike and name the likely source.
4. **Post the tile**: Total stars is the headline, with 12 weekly totals as history (on the first run, count back 12 weeks from the same query). New stars, the busiest day and the top referrer go in the glance.

## Route B: the browser

### What you need

- Signed in to GitHub with push access to the repository; Insights > Traffic is hidden otherwise. The star count itself needs no access on a public repository.

If something is missing, say what and stop; do not invent numbers.

### Steps

Start at https://github.com/. The user is signed in already; never type passwords or codes, and ask if a sign-in page appears.

1. **Read the total**: Open the repository page. The number next to the **Star** button is the current total; click it to see the exact count on the stargazers page when it is rounded (for example `12.5k`).
2. **Work out the week's gain**: GitHub's pages show no star dates, so compare the total with the one you saved last Monday; the difference is the net gain. Keep 12 Mondays of totals for the trend.
3. **Read the referrers**: Open **Insights > Traffic**. The **Referring sites** table lists the top referrers over the last 14 days with views and unique visitors; **Popular content** shows which pages they landed on.
4. **Spot the spike**: The traffic chart on the same page shows views per day for 14 days. A day with more than three times the daily average is the spike; name the referrer most likely behind it.

Note: The UI gives no per-day star counts, so the browser route cannot show stars per weekday; it reports the weekly net gain and uses daily traffic as the proxy. The API route counts individual stars by date from the GraphQL stargazers list.

## The report

- **Total stars** and the gain this week, with a 12-week trend.
- **New stars per day** last week.
- **Top referrers** over the last 14 days.
- One line on what drove the week, for example "Tuesday brought 131 stars".

## Post it to Briefkin

When `BRIEFKIN_TOKEN` is set, or `~/.config/briefkin/env` exists (the installer from https://briefkin.dev/docs writes it), also send the result to the user's Briefkin board as one card. Keep the `item_key` the same on every run so the card updates in place, use a new `event_id` per run, and put today's real numbers in place of the example ones. If the request fails, say so once and carry on.

```bash
[ -n "${BRIEFKIN_TOKEN:-}" ] || . ~/.config/briefkin/env
curl -sS -X POST "${BRIEFKIN_URL:-https://briefkin.dev}/v1/events" \
  -H "authorization: Bearer $BRIEFKIN_TOKEN" \
  -H "content-type: application/json" \
  -d @- <<'JSON'
{
  "v": 1,
  "event_id": "github-stars-tracker/<date of this run, e.g. 2026-10-16>",
  "item_key": "github-stars-tracker",
  "project": "acme-web",
  "source": "GitHub stars tracker skill",
  "kind": "metric",
  "title": "+342 stars this week",
  "metric": {
    "label": "GitHub stars",
    "value": 12486,
    "better": "higher",
    "period_start": "<start of the period, ISO 8601>",
    "period_end": "<end of the period, ISO 8601>"
  },
  "glance": [
    {
      "type": "Grid",
      "props": {
        "columns": 3
      },
      "children": [
        {
          "type": "Stat",
          "props": {
            "label": "New this week",
            "value": 342,
            "delta": 53
          }
        },
        {
          "type": "Stat",
          "props": {
            "label": "Busiest day",
            "value": "Tue, 131"
          }
        },
        {
          "type": "Stat",
          "props": {
            "label": "Top referrer",
            "value": "Hacker News"
          }
        }
      ]
    }
  ],
  "widget": [
    {
      "type": "Bars",
      "props": {
        "unit": "stars",
        "items": [
          {
            "label": "Mon",
            "value": 38
          },
          {
            "label": "Tue",
            "value": 131
          },
          {
            "label": "Wed",
            "value": 74
          },
          {
            "label": "Thu",
            "value": 41
          },
          {
            "label": "Fri",
            "value": 26
          },
          {
            "label": "Sat",
            "value": 15
          },
          {
            "label": "Sun",
            "value": 17
          }
        ]
      }
    },
    {
      "type": "Table",
      "props": {
        "columns": [
          "Referrer",
          "Views",
          "Unique visitors"
        ],
        "align": [
          "left",
          "right",
          "right"
        ],
        "rows": [
          [
            "news.ycombinator.com",
            4210,
            3580
          ],
          [
            "github.com",
            2940,
            1870
          ],
          [
            "Google",
            1320,
            1050
          ],
          [
            "reddit.com",
            860,
            720
          ]
        ]
      }
    },
    {
      "type": "Callout",
      "props": {
        "text": "Tuesday brought 131 stars. Hacker News was the top referrer over the last 14 days, with 3,580 unique visitors.",
        "tone": "info"
      }
    }
  ],
  "size": "md"
}
JSON
```

Widgets come from the Briefkin catalog (https://briefkin.dev/v1/catalog). Without a token, just give the user the report.

Set `period_start` and `period_end` to the window the number covers: the tile names it from them ("Last 7 days", "Today", "This month"). For a count right now (open items, a balance), send `"period_label": ""` so no period shows; for another name, send it as `period_label` (at most 24 characters).

## Run it on a schedule

Suggested: Mondays at 9:00 (`0 9 * * 1`). From cron, with the agent signed in on that machine:

```bash
0 9 * * 1 claude -p "Run the github-stars-tracker skill"
# Codex: codex exec, Gemini CLI: gemini -p, Copilot CLI: copilot -p, OpenCode: opencode run
```

Or use the agent's own scheduler (Claude Code routines, Codex automations, Claude or ChatGPT scheduled tasks): https://briefkin.dev/skills/github-stars-tracker#schedule

Source: https://briefkin.dev/skills/github-stars-tracker
