GitHubHero is a full-stack application written mostly in python that processes your GitHub contributions (from the CLI using GraphQL) and visualizes how your preferred languages have evolved year to year.
Built with Docker, FastAPI, and Poetry for development reproducibility and Streamlit, Plotly, and Pandas interactive data visualization. (FYI, Claude is awesome at generating single page streamlit apps)
Every developer/engineer I've met has followed a different path that has led them to who they are today. We are all unique and always changing.
This tool is for developers who want to introspect on their GitHub history.
It's not about comparing yourself against something (there are no other metrics), it's about you; The unique path you've taken to become the developer you are today.
- 📊 Contribution summary: Commits, PRs, issues, and reviews by year
- 🏷️ Repo language breakdown: Language composition per repo/year
- 🔀 Sankey visualization: Year-over-year language flow
- 🎛️ Interactive filtering: Select top N languages
- 🐳 Containerized: Built with Docker containers (FastAPI and Streamlit)
- 🧠 Offline/online modes: Use live API or download the JSON and run locally.
| Sankey Diagram (Top 5 Languages) |
|---|
 |
(Why's this look different than the streamlit app? This image is from a companion repo which is frontend focused.
Want to see your contributions in the same format or learn how this particular sankey data viz was made?
Check out jrbrowning.github.io repo.
(With both of these repos, you can publish this exact same image of your history to <your username>.github.io!)
git clone https://github.com/jrbrowning/githubhero.git
cd githubheroSet environment variables in .env:
cp .env.sample .envGo to Token Settings
🔗 Visit: https://github.com/settings/tokens
-
Click “Generate new token (classic)”.
-
Set Token Name and Expiration • Note: Choose a descriptive name like githubhero-token • Expiration: Select an minimal expiration date (e.g. 30 days) as a good practice. You can always generate another at a later date!
-
Select Required Scopes. Your token must have:
-
repo- Access private repositories -
read:user- To identify the user or get public profile info -
read:org- (optional) Access organization details (repos, teams, etc)(Don’t select admin, write, or workflow scopes)
You must be:
- A collaborator on the private repo or
- A member of a team with access to the repo
You must use a personal access token (PAT) that is:
- Owned by the user making the request
- Installed correctly if using a GitHub App
-
Generate and Copy the Token
- Click “Generate token”, then copy it immediately. You won’t be able to see it again later.
-
Add your token to env
GITHUB_TOKEN=ghp_...
This app is built using Docker running on Mac Silicon (M4).
docker-compose build; docker-compose upFastAPI swagger docs (autogenerated by FastAPI)
Streamlit App
.
├── api/ # FastAPI backend
├── streamlit/ # Streamlit frontend
├── githubhero/ # Core data processing for API including GraphQL
├── .env # API keys and config
├── docker-compose.yml # Container orchestration
├── pyproject.toml # Poetry dependency and config
Debug mode supported via debugpy (port 5678).
- VSCODE
Import "pandas" could not be resolved from sourcePylancereportMissingModuleSource
--> This means your local shell ENV doesn't have pandas install. Want to create a venv with all the dependencies? Check out the python ENV source script in the (toolshed)
Built mostly by AI (Claude 3.7/4.0 Sonnet, OpenAI GPT-4o/4.1, MS VSCode CoPilot) with human direction and decision making.
Human director Jeff Browning — who is powered by curiosity and coffee ☕.