Git-Me-Stats

Live Demo →

An open-source GitHub profile intelligence dashboard, because your GitHub profile should tell your story, not broken widgets.

Built with Python + FastAPI. Pulls live data from the GitHub API and renders animated stat cards you can embed directly in any README.

---

What it does

Module	Description
Overview	Stars, forks, followers, repos, animated counters
Streak	Current + longest streak, contributions this period
Top Languages	Recency + star weighted, Jupyter merged into Python
Stack Fingerprint	Radar chart of your language distribution
Contribution Heatmap	52-week activity grid
Top Repos	Sorted by stars with descriptions and links

All modules support time range filtering All time, Last 12 months, YTD, Last 90 days.

---

Embed cards in your README

After searching a profile, hover any card and click ⋯ to get your embed snippet. Paste it directly into your README:

<div align="center">

<p><img src="https://git-me-stats-production.up.railway.app/card/yourname/overview?theme=midnight" /></p>

<p><img src="https://git-me-stats-production.up.railway.app/card/yourname/streak?theme=midnight" /></p>

<p><img src="https://git-me-stats-production.up.railway.app/card/yourname/langs?theme=midnight" /></p>

<p><img src="https://git-me-stats-production.up.railway.app/card/yourname/radar?theme=midnight" /></p>

</div>

Available card endpoints

Endpoint	Description
/card/{username}/overview	Profile + key metrics
/card/{username}/streak	Contribution streak
/card/{username}/langs	Top languages
/card/{username}/radar	Stack fingerprint radar
/card/{username}/repos	Top repositories

Parameters

Param	Options	Default
theme	default midnight ocean forest sunset rose	default
range	all year ytd 90d	all

---

Run it locally

Prerequisites: Python 3.11+

# 1. Clone
git clone https://github.com/ChristianLG2/git-me-stats.git
cd git-me-stats

# 2. Create virtual environment
python -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate

# 3. Install dependencies
pip install -r requirements.txt

# 4. Add your GitHub token (optional but recommended)
cp .env.example .env
# Open .env and set GITHUB_TOKEN=ghp_...

# 5. Start the server
python run.py

# 6. Open http://127.0.0.1:8000

Why a token? Without one, GitHub limits you to 60 API requests/hour per IP. A token (no scopes needed) raises it to 5,000/hr and unlocks exact contribution data via GraphQL.

Get one at github.com/settings/tokens → Generate new token (classic) → no scopes needed.

---

API

The backend is a clean REST API you can call directly.

GET /api/stats/{username}?range=ytd&overview=true&langs=true

Param	Type	Default	Description
range	string	all	all year ytd 90d
overview	bool	true	Profile + metrics
langs	bool	true	Language breakdown
repos	bool	true	Top repositories
streak	bool	true	Streak data
contrib	bool	true	Heatmap data
token	string	—	Your GitHub PAT

# Example
curl "https://git-me-stats-production.up.railway.app/api/stats/torvalds?range=ytd"

---

Project structure

git-me-stats/
├── app/
│   ├── main.py                   # FastAPI app entry point
│   ├── routes/
│   │   ├── stats.py              # GET /api/stats/{username}
│   │   ├── cards.py              # GET /card/{username}/{type}
│   │   └── ui.py                 # Serves the dashboard
│   ├── services/
│   │   ├── github_service.py     # GitHub REST + GraphQL logic
│   │   └── svg_service.py        # SVG card renderers
│   ├── templates/
│   │   └── index.html
│   └── static/
│       ├── css/style.css
│       └── js/app.js
├── tests/
│   └── test_github_service.py
├── run.py                        # Windows-friendly entry point
├── requirements.txt
├── .env.example
└── .gitignore

---

Running tests

PYTHONPATH=. pytest

Tests use unittest.mock — no network calls, no token needed.

---

Deploy your own

Works on any platform that runs Python. Recommended options:

Platform	Notes
Railway	Connect repo → add GITHUB_TOKEN env var → deploy. Auto-deploys on push.
Render	Free tier available. Start command: uvicorn app.main:app --host 0.0.0.0 --port $PORT
Fly.io	fly launch then fly secrets set GITHUB_TOKEN=ghp_...

---

Contributing

Found a bug? Missing a feature? Want to add a new card type or theme?

Fork it. Fix it. PR it. Contributions are always welcome.

1. Fork the repo
2. Create a branch (git checkout -b feature/my-idea)
3. Make your changes + add tests if relevant
4. Open a pull request

Some ideas if you're looking for a place to start:

• New card types (heatmap card, repos card)
• More themes
• Caching layer to reduce API calls
• Better streak accuracy via GraphQL

---

License

MIT