📕 How to use GitHub Star History

When choosing a tool (especially an open-source one) to use, what's your thought process? What are the factors that matter to you?

• Any other users out there?
• Is it the most popular in this category?
• Is this technology in decline?

Here's one obvious metric I'm sure you will also investigate: its GitHub stars.

You can't fully trust a project's GitHub stars alone. It is, however, a good way to determine if a tool is an adequate one and if it's likely to grow, if you use it correctly.

Even if a project has hundreds of millions of stars now, doesn't mean that it's still gaining popularity or maintained. Or if the project had an explosive breakout in the past? There's no way of knowing these simply from gazing at the stars count. Here's when Star History comes in handy: it shows how the number of GitHub stars of a project is increasing over the years. And - it's free and open-source.

How to add a repo

To add a repo, type in the search bar and click View star history. Three input formats are supported:

1. Full URL: https://github.com/star-history/star-history
2. Short form: star-history/star-history
3. Org-only (when repo name matches org name): star-history

For something like hashicorp/terraform, you need to specify the full hashicorp/terraform since the org and repo names don't match.

You can also paste multiple repos at once, separated by commas.

How to compare multiple repos

After adding one repo, continue typing the next repo in the input box. They will all be rendered in the same chart.

Each repo appears as a pill-shaped badge below the input. You can:

• Toggle visibility: Click a repo name to show/hide it in the chart (hidden repos appear with a strikethrough).
• Remove a repo: Click the X button on the badge.
• Clear all: Click "Clear all" to start fresh.

How to align the timeline

Check Align timeline above the chart to switch from calendar time (Date mode) to days-since-first-star (Timeline mode). This lets you compare the growth trajectories of repos that started at different times.

Log scale

Check Log scale to switch the Y-axis to logarithmic scale. This is useful when comparing repos with vastly different star counts — it makes it easier to see growth patterns across different magnitudes.

Legend position

Use the Legend radio buttons to place the legend at Top left (default) or Bottom right, depending on where the chart lines are.

How to export

Below the chart, you'll find these action buttons:

• Image: Download the chart as a PNG image.
• CSV: Export the raw star history data as a CSV file.
• Link: Copy the current URL (with all chart state encoded in query params) to share with others.
• Share: Share the chart on X (Twitter).

How to add your GitHub access token

Star History reads star data from the GitHub API. Since GitHub restricted the stargazers endpoint (July 2026) to a repository's own admins and collaborators, star history is now only available for repos you own or collaborate on — and you'll need an access token that can read them. A token also raises your API rate limit.

Choose one:

Fine-grained token — least access, but a single owner. A fine-grained token is scoped to one account or org — it cannot read repos across different orgs. Best when your chart only covers repos under a single owner:

1. Create a fine-grained token.
2. Set Resource owner to the account or org that owns the repo(s).
3. Set Repository access to the repo(s) you want (or All repositories).
4. Under Permissions → Repository permissions, grant only Metadata → Read-only. That is the only permission the stargazers endpoint requires, so the token can do nothing else.

Classic token — works across orgs. Covers every repo you own or collaborate on in any org, all with a single token — so this is the one to use when a chart mixes repos from different orgs. It grants broader write access to your public repos, so treat it with care:

1. Create a classic token.
2. Under Select scopes, tick public_repo.

Charting repos from different orgs in one view? A fine-grained token only reaches a single owner, so use a classic token — for example, plotting bytebase/bytebase and star-history/star-history together requires one.

Then, on star-history.com, click Add access token in the header, paste your token, and hit Save.

Your token is stored only in your browser's local storage — it is never sent to Star History servers.

Tokens with no scopes no longer work — not even for your own repositories. If you created one before, replace it using one of the options above.

How to embed the chart in your README

The Show real-time chart on your README.md section below the chart generates a live chart image for your README. Since GitHub restricts star data to a repo's admins and collaborators, you supply a token that can read the repo:

1. Create a fine-grained token — it goes into your public README, so least access is safest.
2. Paste it in and click Generate embed code. The token is encrypted, so only the encrypted value appears in your README.
3. Copy the GitHub README.md format.

Each time your README is viewed, our server decrypts the token in memory to read your stars, then discards it — never stored, never logged.

The embed keeps your current chart settings and re-renders with the latest stars on each view.

Chrome extension

We also have a Chrome extension. Install it, then go to any GitHub repo and click the extension icon — a star history chart will pop up right there.

---

Play around and let us know @StarHistoryHQ what you think!