Warpchart: Live GitHub Repository Growth Telemetry and Star Ranking

Introduction

Warpchart is an innovative open-source tool designed to provide live growth telemetry for any GitHub repository. It transforms raw star data into a dynamic, interactive star chart, visualizing your repository's journey through the worldwide ranking, complete with real-time updates and an optional soundscape. While GitHub offers basic star data, Warpchart provides a comprehensive "flight console" to monitor your project's visibility and growth in unprecedented detail.

It addresses the limitations of static star history charts and opaque trending lists by offering a clear view of your repository's position, velocity, and surrounding projects in the global ranking. With features like a live status bar, an interactive star chart, and "scan cards" for neighboring repos, Warpchart empowers maintainers with deep insights into their project's trajectory.

Explore the live demo tracking career-ops or instantly scan any repository by visiting warpchart.dev/r/owner/name.

Why Use Warpchart?

Warpchart goes beyond basic star counts, offering a rich set of features that provide actionable insights into your repository's growth:

• Real-time Telemetry: Get live updates on stars, worldwide rank, velocity, and estimated time to reach the next milestone.
• Interactive Star Chart: Visualize your repository's position relative to others in a two-band space map, showing ranking neighbors and potential overtake targets.
• Spike Forensics: Automatically correlate star spikes with Hacker News posts, Reddit discussions, and your releases, helping you understand what drives growth.
• Unique Soundscape: Experience a fully synthesized Web Audio soundscape where each new star is a sonar ping, and milestone crossings play a quiet fanfare.
• Comprehensive Data: Access velocity metrics, daily ladders, cumulative charts, heatmaps, and rank over time, providing a full instrument panel for growth analysis.
• Shareable Insights: Easily embed badges and animated charts into your READMEs, and share dynamic Open Graph cards with live stats.
• Developer-Friendly: Access all telemetry via a public, free, and cache-only REST API, an MCP server, and a powerful CLI.

Warpchart provides the cockpit GitHub doesn't, allowing you to truly understand and react to your project's journey in the open-source world.

Installation and Setup

Setting up Warpchart for your repository is designed to be quick and straightforward, taking just about five minutes:

1. Use as a Template: Start by using the Warpchart repository as a template for your new project.
2. Configure mission.config.json: Edit the mission.config.json file to specify your repository's owner/name and an accent color.

   { "repo": "owner/name", "accent": "cyan" }

3. Run Bootstrap: Navigate to the "Actions" tab in your GitHub repository and run the bootstrap workflow. Alternatively, you can run it locally:

   GH_TOKEN=$(gh auth token) node collector/bootstrap.mjs

   After running locally, commit the data/ directory.

4. Deploy to Vercel: Import your repository into Vercel. Add a GITHUB_TOKEN environment variable, which should be a fine-grained Personal Access Token (PAT) with read-only access to public repositories.
5. Done: The hourly collect workflow will automatically maintain your repository's history and trigger redeployments on Vercel.

For local development, simply run:

npm install
GITHUB_TOKEN=$(gh auth token) npm run dev

Examples

Warpchart provides multiple ways to access its powerful telemetry, catering to developers, agents, and maintainers alike.

CLI Usage

The command-line interface offers quick access to key metrics:

npx warpchart vuejs/core              # rank, velocity, a braille star chart + who's hunting it
npx warpchart hunters d3/d3           # who's about to pass it (and who it's about to pass)
npx warpchart top 20 --lang Rust      # the biggest repos, optionally by language
npx warpchart velocity --lang Go      # the fastest-growing repos right now
npx warpchart compare react/react vuejs/core
npx warpchart embed OWNER/NAME        # a README embed snippet
npx warpchart vuejs/core --json       # raw JSON (agent friendly)

REST API

Access telemetry programmatically via the public, cache-only REST API at /api/v1:

curl "https://warpchart.dev/api/v1/repo?repo=vuejs/core"          # rank, velocity, neighbours, next gate
curl "https://warpchart.dev/api/v1/leaderboard?language=Rust"     # biggest repos, optionally by language
curl "https://warpchart.dev/api/v1/velocity?limit=20&language=Go" # fastest movers, optionally by language
curl "https://warpchart.dev/api/v1/overtakes?repo=d3/d3"          # who is hunting a repo (and who it's about to pass)
curl "https://warpchart.dev/api/v1/compare?repos=vuejs/core,react/react"
curl "https://warpchart.dev/api/v1/embed?repo=OWNER/NAME"         # README embed snippet

The GET /api/v1 endpoint provides a self-documenting index.

Embeddable Assets

Easily share your repository's growth with dynamic badges and animated charts:

Embeddable Badge (SVG)

[![World rank](https://warpchart.dev/api/badge?repo=OWNER/NAME)](https://warpchart.dev/r/OWNER/NAME)

Embeddable Animated Chart (SVG)

<a href="https://warpchart.dev/r/OWNER/NAME" target="_blank">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="https://warpchart.dev/api/chart?repo=OWNER/NAME&theme=dark">
    <img alt="Live star telemetry" src="https://warpchart.dev/api/chart?repo=OWNER/NAME&theme=light" loading="lazy">
  </picture>
</a>

Links

• GitHub Repository: santifer/warpchart
• Live Demo: warpchart.dev
• License: MIT License