GitHub Contribution Graph in your terminal โ€” for hackers who prefer Unicode over UI

Navigation

Verified details

These details have been verified by PyPI
Maintainers
Avatar for Gizmet from gravatar.com Gizmet

Unverified details

These details have not been verified by PyPI
Project links
Meta
  • License: MIT License (MIT)
  • Author: Gizmet
  • Maintainer: Gizmet
  • Tags github , terminal , heatmap , contributions , cli , rich
  • Requires: Python >=3.9
  • Provides-Extra: dev
Classifiers
Report project as malware

Project description

GitHub Stats Heatmap Logo

๐Ÿ•ต๏ธโ€โ™‚๏ธ GitHub Stats Heatmap

Your GitHub activity, visualized โ€” hacker style.

PyPI Python versions License: MIT CI

Features โ€ข Quick Start โ€ข Installation โ€ข Live Refresh โ€ข Plugins โ€ข Roadmap โ€ข Contributing โ€ข Changelog

โšก TL;DR

  • What: Terminal-based GitHub contribution heatmap viewer
  • Why: Instantly visualize your GitHub activity in your terminal, hacker style
  • How: 
    pipx install gh-stats-heatmap
gh-stats-heatmap
  • Features: Live refresh, plugin system, global leaderboards, themes, analytics, compare mode, and more!
  • Platforms: macOS, Linux, Windows

Get Started โ†“

๐Ÿ†• What's New

๐Ÿ–ผ๏ธ UI & Legend Improvements (v1.0.2)

  • Legend is now a high-contrast Rich panel: Instantly see what each block means, with clear colors and a plain-language explanation.
  • Improved accessibility and readability for all terminal themes.

๐ŸŽ‰ Package Successfully Published! (v1.0.1)

The GitHub Stats Heatmap tool is now available on PyPI with easy installation methods!

Installation Options:

  • ๐Ÿš€ pipx (Recommended): pipx install gh-stats-heatmap
  • ๐ŸŒ PyPI: pip install gh-stats-heatmap
  • ๐Ÿบ Homebrew: brew tap gizmet/tap && brew install gizmet/tap/ghstats

โšก Live Refresh Mode

Experience real-time GitHub stats with auto-updating displays! Perfect for demos, monitoring, and live presentations.

New Features:

  • ๐Ÿ”„ Real-time Updates: Auto-refresh every 30+ seconds
  • ๐Ÿ›ก๏ธ Rate Limit Protection: Smart handling of GitHub API limits
  • ๐ŸŽญ Demo Mode: Seamless fallback to realistic sample data
  • ๐Ÿ“Š Status Indicators: Clear visual feedback (LIVE/RATE LIMITED/DEMO)
  • ๐Ÿ’พ Data Caching: Maintains display even when API is unavailable
# Try it now!
ghstats yourusername --live

See the Live Refresh Mode section for complete details.

โœจ Features

Category Features
๐ŸŽฏ Core Zero-config heatmaps โ€ข Rich terminal output โ€ข Cross-platform
๐ŸŽจ Themes GitHub, dark, light, matrix, cyberpunk, monochrome โ€ข Custom JSON themes
๐Ÿ–ผ๏ธ UI High-contrast, panel-based legend for easy interpretation
๐Ÿ“Š Analytics Streaks, trends, busiest month, activity patterns โ€ข Multiple sparklines โ€ข Advanced analytics โ€ข Smart insights
๐Ÿ”„ Compare Side-by-side user comparison โ€ข Per-user themes โ€ข Diff highlighting โ€ข Overlap analysis
๐Ÿ† Leaderboards Repository/organization contributors โ€ข Global top contributors
๐Ÿ”Œ Plugins Extensible plugin system โ€ข Global leaderboard plugin
๐ŸŽฎ TUI Interactive terminal UI โ€ข Multiple views โ€ข Cell selection โ€ข Theme switching
โšก Live Real-time refresh mode โ€ข Auto-updating displays โ€ข Rate limit protection โ€ข Demo mode โ€ข Smart caching

Tip: The heatmap legend is now always clear and easy to read, with high-contrast colors and a plain-language explanationโ€”perfect for all terminal backgrounds and accessibility needs.

๐Ÿš€ Quick Start

# Install with pipx (easiest)
pipx install gh-stats-heatmap

# Or install from PyPI
pip install gh-stats-heatmap

# Instant visualization
ghstats yourusername

# Compare two developers
ghstats user1 --compare user2

# With global context
ghstats username --global-leaderboard --token YOUR_TOKEN

# Live refresh for demos
ghstats username --live

# Live refresh with custom interval
ghstats username --live --refresh-interval 60

๐Ÿ“ฆ Installation

๐Ÿš€ pipx Install (Recommended for CLI tools)

# Install pipx if you don't have it
pip install pipx
pipx ensurepath

# Install ghstats
pipx install gh-stats-heatmap

๐ŸŒ PyPI Install

pip install gh-stats-heatmap

๐Ÿบ Homebrew Install (macOS/Linux)

# Add the tap
brew tap gizmet/tap

# Install ghstats
brew install gizmet/tap/ghstats

You can also view and contribute to the Homebrew formula at: https://github.com/Gizmet/homebrew-tap

๐Ÿ”ง From Source

git clone https://github.com/Gizmet/github-contribution-heatmap-viewer
cd github-contribution-heatmap-viewer
pip install -e .

๐ŸŽฏ Usage Examples

Command Result
ghstats torvalds View Linus's contributions
ghstats gizmet --theme matrix Cyberpunk-style heatmap
ghstats user1 --compare user2 Side-by-side comparison
ghstats user1 --compare user2 --theme dark --theme2 matrix Enhanced comparison with different themes
ghstats --plugin global-leaderboard Top GitHub contributors
ghstats username --tui Interactive TUI mode
ghstats username --live Real-time updates
ghstats username --live --refresh-interval 30 Custom refresh interval
ghstats username --watch Watch mode (alias for --live)

๐Ÿ”Œ Plugin System

Available Plugins

ghstats --list-plugins

๐ŸŒ Global Leaderboard Plugin

Shows top GitHub contributors worldwide using GraphQL API:

# Standalone plugin
ghstats --plugin global-leaderboard --token YOUR_TOKEN

# Integrated with heatmap
ghstats username --global-leaderboard --token YOUR_TOKEN

Features:

  • ๐Ÿ”„ Resilient - Retry logic, fallback data, network error handling
  • ๐Ÿ“Š Rich Data - Contributions, followers, rankings
  • ๐ŸŽจ Beautiful Output - Formatted tables with proper alignment
  • โšก Fast - Optimized GraphQL queries with pagination

๐ŸŽฎ Interactive TUI Mode

Experience your GitHub stats with an interactive terminal interface:

# Launch TUI mode
ghstats username --tui

# TUI with custom theme
ghstats username --tui --theme matrix

# TUI with API token
ghstats username --tui --token YOUR_TOKEN

Features:

  • ๐Ÿ“Š Multiple Views: Heatmap, stats, compare, and settings views
  • ๐ŸŽฏ Interactive Navigation: Switch views and explore data
  • ๐ŸŽจ Theme Switching: Change themes on the fly
  • ๐Ÿ“ˆ Detailed Analytics: Comprehensive statistics tables
  • ๐Ÿ”„ Data Refresh: Reload data without restarting

Navigation:

  • h = Heatmap view
  • s = Stats view
  • v = Compare view
  • o = Settings view
  • t = Change theme
  • r = Refresh data
  • q = Quit

See TUI.md for complete documentation.

๐ŸŽจ Themes

Built-in Themes

  • github - GitHub's official colors
  • dark - Dark terminal aesthetic
  • light - Light terminal friendly
  • matrix - Green terminal matrix vibe
  • cyberpunk - Neon magenta/yellow/cyan
  • monochrome - Clean black and white

Custom Themes

Create your own with JSON:

{
  "name": "My Theme",
  "colors": ["#ebedf0", "#9be9a8", "#40c463", "#30a14e", "#216e39"]
}

๐Ÿ“ˆ Sample Output

โ•ญโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ ๐Ÿ•ต๏ธโ€โ™‚๏ธ GitHub Stats Heatmap โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ•ฎ
โ”‚                                                                                           โ”‚
โ”‚  GitHub Contributions: torvalds (Past 52 Weeks)                                           โ”‚
โ”‚                                                                                           โ”‚
โ”‚  M  โ–“โ–ˆโ–ˆโ–ˆโ–“โ–“โ–ˆโ–“โ–’โ–“โ–ˆโ–“โ–“โ–ˆโ–ˆโ–ˆโ–ˆโ–’โ–‘โ–ˆโ–“โ–ˆโ–’โ–ˆโ–“โ–ˆโ–“โ–ˆโ–’โ–“โ–ˆโ–’โ–ˆโ–“โ–“โ–‘โ–ˆโ–ˆโ–“โ–ˆโ–’โ–ˆโ–ˆโ–ˆโ–ˆโ–“โ–ˆโ–“โ–ˆโ–ˆโ–ˆโ–“                                  โ”‚
โ”‚  T  โ–ˆโ–“โ–’โ–’โ–’โ–’โ–‘โ–’โ–ˆโ–ˆโ–’โ–’โ–’โ–“โ–’โ–’โ–’โ–ˆโ–ˆโ–‘โ–“โ–“โ–’โ–’โ–“โ–’โ–ˆโ–ˆโ–“โ–’โ–’โ–’โ–’โ–’โ–’โ–ˆโ–ˆโ–“โ–“โ–’โ–“โ–“โ–“โ–‘โ–ˆโ–ˆโ–’โ–“โ–“โ–’โ–’โ–‘                                  โ”‚
โ”‚  W  โ–ˆโ–“โ–’โ–’โ–“โ–’โ–’โ–’โ–ˆโ–ˆโ–‘โ–’โ–’โ–‘โ–“โ–‘โ–“โ–ˆโ–ˆโ–’โ–“โ–“โ–’โ–‘โ–’โ–“โ–ˆโ–ˆโ–’โ–’โ–’โ–“โ–ˆโ–ˆโ–’โ–ˆโ–ˆโ–“โ–’โ–’โ–ˆโ–’โ–“โ–“โ–ˆโ–ˆโ–’โ–ˆโ–’โ–“โ–ˆโ–‘                                  โ”‚
โ”‚  T  โ–“โ–‘โ–’โ–“โ–‘โ–“โ–ˆโ–“โ–ˆโ–ˆโ–“โ–’โ–“โ–’โ–’โ–“โ–“โ–ˆโ–ˆโ–’โ–’โ–“โ–‘โ–’โ–’โ–‘โ–ˆโ–ˆโ–’โ–’โ–’โ–ˆโ–“โ–“โ–’โ–ˆโ–ˆโ–’โ–ˆโ–ˆโ–“โ–“โ–ˆโ–’โ–ˆโ–ˆโ–’โ–ˆโ–“โ–“โ–’โ–‘                                  โ”‚
โ”‚  F  โ–ˆโ–’โ–“โ–“โ–’โ–“โ–ˆโ–ˆโ–ˆโ–ˆโ–“โ–“โ–ˆโ–ˆโ–“โ–“โ–’โ–ˆโ–ˆโ–ˆโ–“โ–ˆโ–“โ–’โ–’โ–ˆโ–ˆโ–ˆโ–’โ–ˆโ–ˆโ–’โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–“โ–’โ–“โ–ˆโ–ˆโ–ˆโ–ˆโ–“โ–ˆโ–“โ–“โ–“โ–‘                                  โ”‚
โ”‚  S  โ–ˆโ–ˆโ–ˆโ–ˆโ–“โ–“โ–ˆโ–“โ–“โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–“โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–“โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–“โ–ˆโ–ˆโ–ˆโ–‘                                  โ”‚
โ”‚  S  โ–ˆโ–’โ–“โ–ˆโ–ˆโ–ˆโ–’โ–’โ–“โ–ˆโ–ˆโ–’โ–ˆโ–‘โ–’โ–’โ–“โ–’โ–ˆโ–“โ–ˆโ–ˆโ–’โ–’โ–“โ–’โ–ˆโ–“โ–ˆโ–ˆโ–ˆโ–ˆโ–’โ–“โ–“โ–ˆโ–’โ–“โ–ˆโ–ˆโ–’โ–ˆโ–ˆโ–“โ–ˆโ–“โ–“โ–ˆโ–“โ–“โ–“โ–‘                                  โ”‚
โ”‚                                                                                           โ”‚
โ”‚  Weekly Activity: โ–„โ–‚โ–‚โ–‚โ–‚โ–‚โ–ƒโ–โ–†โ–…โ–ƒโ–‚โ–‚โ–‚โ–‚โ–‚โ–‚โ–‡โ–„โ–‚โ–‚โ–ƒโ–โ–‚โ–‚โ–‚โ–‡โ–„โ–‚โ–‚โ–‚โ–‚โ–ƒโ–ƒโ–‚โ–ˆโ–…โ–‚โ–ƒโ–ƒโ–‚โ–‚โ–ƒโ–‚โ–‡โ–„โ–‚โ–ƒโ–‚โ–‚โ–‚โ–              โ”‚
โ”‚  Monthly Trend: โ–โ–โ–โ–โ–ˆโ–‚                                                                     โ”‚
โ”‚  Consistency: โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ƒโ–โ–โ–โ–โ–                           โ”‚
โ”‚  Trend: ๐Ÿ“ˆ Accelerating | Peak: This week (24 contributions) | Consistency: โœ… Good (85%)   โ”‚
โ”‚                                                                                           โ”‚
โ”‚  Legend: โ–‘ = 0 โ–’ = 1-3 โ–“ = 4-6 โ–ˆ = 7+                                                     โ”‚
โ”‚                                                                                           โ”‚
โ”‚  โšก Current streak: 1 days | ๐Ÿ“Š Total contributions: 2885 | ๐Ÿ“… Active days: 344/364       โ”‚
โ”‚  (94.5%) | ๐Ÿ† Longest streak: 66 days | ๐Ÿ“ˆ This month: 170 | ๐Ÿ“‰ Inactive weeks: 0 | ๐Ÿ“…    โ”‚
โ”‚  Busiest week: 157 contributions (Week 36) | ๐Ÿฅ‡ Most active weekday: S | ๐ŸŒŸ Busiest       โ”‚
โ”‚  month: May | ๐Ÿ˜ด Least active weekday: T | ๐Ÿ“† Avg/week: 55.5 | ๐Ÿ“ˆ Trend: Up (+241)        โ”‚
โ”‚                                                                                           โ”‚
โ”‚  ๐ŸŽฏ Consistency: 85/100 | โšก Pattern: Weekday focused (Monday peak, Tuesday low)           โ”‚
โ”‚  ๐ŸŒฑ Seasonal: Strong Summer preference | ๐Ÿš€ Momentum: +25% | ๐ŸŒ… Weekend work: 15%         โ”‚
โ”‚  โฐ Peak hours: Early week focus (Monday peak) | ๐Ÿ˜ด Burnout risk: Low (healthy pace)      โ”‚
โ”‚  ๐ŸŽฏ Improvement: High potential (few gaps)                                                โ”‚
โ”‚                                                                                           โ”‚
โ”‚  ๐Ÿ’ญ You've contributed 2885 times in the last 52 weeks. Your consistency is excellent.    โ”‚
โ”‚  You're a weekday warrior. You show a strong summer preference. You're gaining momentum.  โ”‚
โ”‚  You prefer weekday work. You have great potential for growth. You're on a 1-day streak   โ”‚
โ”‚  with increasing activity.                                                                 โ”‚
โ”‚                                                                                           โ”‚
โ”‚  ๐ŸŒ Global GitHub Contributors                                                            โ”‚
โ”‚  โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”             โ”‚
โ”‚  โ”‚ Rank โ”‚ User              โ”‚ Name              โ”‚ Contributions โ”‚ Followers โ”‚             โ”‚
โ”‚  โ”œโ”€โ”€โ”€โ”€โ”€โ”€โ”ผโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ผโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ผโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ผโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ค             โ”‚
โ”‚  โ”‚    1 โ”‚ @Charles-Chrismann โ”‚ Charles Chrismann โ”‚      12,290 โ”‚    16,017 โ”‚              โ”‚
โ”‚  โ”‚    2 โ”‚ @lllyasviel        โ”‚ lllyasviel        โ”‚       9,121 โ”‚    19,979 โ”‚              โ”‚
โ”‚  โ”‚    3 โ”‚ @phodal            โ”‚ Fengda Huang      โ”‚       9,052 โ”‚    20,351 โ”‚              โ”‚
โ”‚  โ”‚    4 โ”‚ @skydoves          โ”‚ Jaewoong Eum      โ”‚       7,045 โ”‚    12,058 โ”‚              โ”‚
โ”‚  โ”‚    5 โ”‚ @jeresig           โ”‚ John Resig        โ”‚       6,066 โ”‚    18,881 โ”‚              โ”‚
โ”‚  โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”ดโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ดโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ดโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ดโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜             โ”‚
โ”‚                                                                                           โ”‚
โ•ฐโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ•ฏ

๐Ÿ› ๏ธ API Tokens

๐Ÿ”‘ When You Need GitHub API Tokens

Required for:

  • ๐Ÿ”’ Private repository data - Access to private repo contributions
  • ๐Ÿ† Repository leaderboards - Top contributors in specific repos
  • ๐Ÿข Organization leaderboards - Contributors within organizations
  • ๐ŸŒ Global leaderboard plugin - Worldwide top GitHub contributors
  • ๐Ÿ“Š Integrated global leaderboard - Combined heatmap + leaderboard
  • ๐Ÿ” Higher rate limits - 5000 requests/hour vs 60 requests/hour

Not required for:

  • โœ… Public profile heatmaps - Basic contribution visualization
  • โœ… Public user statistics - Streaks, trends, patterns
  • โœ… Compare mode - Side-by-side public user comparison
  • โœ… Theme customization - All theme features
  • โœ… Live refresh mode - Auto-updating displays (with rate limits)

๐Ÿš€ Creating a GitHub API Token

  1. Go to GitHub Settings: https://github.com/settings/tokens
  2. Click "Generate new token" โ†’ "Generate new token (classic)"
  3. Set token name: e.g., "ghstats-cli"
  4. Select scopes:
    • โœ… public_repo (for public repository data)
    • โœ… read:org (for organization leaderboards)
    • โœ… read:user (for user profile data)
  5. Click "Generate token"
  6. Copy the token (store it securely - you won't see it again!)

๐Ÿ’ป Using Your Token

# Set as environment variable (recommended)
export GITHUB_TOKEN=your_token_here
ghstats username

# Or pass directly via command line
ghstats username --token your_token_here

# For global leaderboard
ghstats --plugin global-leaderboard --token your_token_here

# Combined heatmap + leaderboard
ghstats username --global-leaderboard --token your_token_here

๐Ÿ”’ Security Best Practices

  • Never commit tokens to version control
  • Use environment variables instead of command line arguments
  • Set minimal permissions - only grant necessary scopes
  • Rotate tokens regularly - regenerate every 90 days
  • Use different tokens for different applications

๐Ÿ“Š Rate Limits

Authentication Rate Limit Use Case
None 60 requests/hour Basic public profiles
Token 5000 requests/hour Full features, private repos

๐Ÿ› ๏ธ Troubleshooting

"API rate limit exceeded"

# Check your rate limit status
ghstats username --token your_token_here

# Wait for reset or use demo mode
ghstats username --live  # Automatically uses demo mode when rate limited

"Not found" for private repos

# Ensure token has correct scopes
ghstats username --token your_token_here

Token not working

# Verify token is valid
curl -H "Authorization: token your_token_here" https://api.github.com/user

๐Ÿ”ง Plugin Development

Extend functionality with custom plugins:

from plugins.base import GhStatsPlugin

class MyPlugin(GhStatsPlugin):
    def name(self) -> str:
        return "my-plugin"
    
    def description(self) -> str:
        return "My custom plugin"
    
    def requires_token(self) -> bool:
        return False
    
    def execute(self, **kwargs) -> Dict[str, Any]:
        # Your plugin logic here
        return {"success": True, "data": "..."}

๐Ÿ“‹ Roadmap

Status Feature Description
โœ… Complete Core heatmap rendering Beautiful terminal output with Unicode blocks
โœ… Complete Theme system Built-in + custom JSON themes
โœ… Complete Statistics engine Streaks, trends, patterns, analytics
โœ… Complete Compare mode Side-by-side user comparison
โœ… Complete Plugin architecture Extensible plugin system
โœ… Complete Global leaderboard Top GitHub contributors worldwide
โœ… Complete Live refresh Real-time updates
๐Ÿ”„ In Progress Export features PNG, HTML, JSON export
๐Ÿ”„ In Progress TUI mode Interactive terminal UI
๐Ÿ“‹ Planned Team analytics Organization insights
๐Ÿ“‹ Planned Historical trends Year-over-year comparisons
๐Ÿ“‹ Planned Custom metrics User-defined contribution types

๐Ÿ—๏ธ Project Structure

github-contribution-heatmap-viewer/
โ”œโ”€โ”€ ghstats.py              # CLI entry point
โ”œโ”€โ”€ github_api.py           # GitHub API integration
โ”œโ”€โ”€ heatmap.py              # Grid generation logic
โ”œโ”€โ”€ render.py               # Rich terminal rendering
โ”œโ”€โ”€ utils.py                # Utility functions
โ”œโ”€โ”€ plugins/                # Plugin system
โ”‚   โ”œโ”€โ”€ __init__.py         # Plugin manager
โ”‚   โ”œโ”€โ”€ base.py             # Base plugin class
โ”‚   โ””โ”€โ”€ global_leaderboard.py # Global leaderboard plugin
โ”œโ”€โ”€ tests/                  # Test suite
โ”œโ”€โ”€ themes/                 # Theme definitions
โ””โ”€โ”€ README.md               # This file

๐Ÿงช Development

# Install in development mode
pip install -e .

# Run tests
pytest

# Run with coverage
pytest --cov=.

# Format code
black .

# Lint code
flake8 .

๐Ÿค Contributing

We welcome contributions! Here's how:

  1. ๐Ÿด Fork the repository
  2. ๐ŸŒฑ Create a feature branch: git checkout -b feature/amazing-thing
  3. ๐Ÿ’ฅ Commit your changes: git commit -m 'Add amazing thing'
  4. ๐Ÿš€ Push to the branch: git push origin feature/amazing-thing
  5. ๐Ÿ“ฌ Open a Pull Request

Guidelines:

  • Follow PEP 8 style guidelines
  • Add tests for new functionality
  • Update documentation for new features
  • Write clear commit messages

๐Ÿ“„ License

This project is licensed under the MIT License - see the LICENSE file for details.

๐Ÿ™ Acknowledgments

  • Rich - Beautiful terminal rendering
  • GitHub API - Data source
  • Unicode - For the glorious โ–‘โ–’โ–“โ–ˆ blocks
  • committers.top - Inspiration for global leaderboards

Made with โค๏ธ for developers who live in the terminal

โญ Star this repo if you find it useful! โญ

โšก Live Refresh Mode

Experience real-time GitHub stats with auto-updating displays perfect for demos, monitoring, and live presentations:

# Basic live refresh (30s minimum interval)
ghstats username --live

# Custom refresh interval
ghstats username --live --refresh-interval 60

# Watch mode (alias for --live)
ghstats username --watch

# Live refresh with compare mode
ghstats username --compare user2 --live

# Live refresh with custom theme
ghstats username --live --theme matrix

๐ŸŽฏ Live Refresh Features

  • ๐Ÿ”„ Auto-Updating: Real-time data refresh with customizable intervals
  • ๐Ÿ›ก๏ธ Rate Limit Protection: Automatic detection and graceful handling of GitHub API rate limits
  • ๐ŸŽญ Demo Mode: Seamless fallback to realistic sample data when rate limited
  • ๐Ÿ“Š Status Indicators: Clear visual feedback (LIVE/RATE LIMITED/DEMO)
  • ๐Ÿ’พ Data Caching: Uses cached data when API calls fail
  • โฐ Smart Intervals: Minimum 30-second intervals to prevent rate limiting
  • ๐ŸŽจ Theme Support: Full theme compatibility in live mode
  • ๐Ÿ”„ Compare Mode: Side-by-side live comparison of multiple users

๐ŸŽญ Demo Mode

When rate limited, the live refresh automatically switches to demo mode:

  • Realistic Data: Generates authentic-looking contribution patterns
  • Weekday Patterns: Higher activity on weekdays, lower on weekends
  • Random Variation: Natural-looking contribution counts and patterns
  • Seamless Transition: No interruption to the live display

๐Ÿ“Š Status Display

Live refresh provides comprehensive status information:

Last update: 14:30:25 | Updates: 15 | Status: LIVE | Next refresh in 60s
Rate limit: 4850/5000 requests remaining | Reset at 15:00:00

Status Types:

  • [green]LIVE[/green] - Real-time data from GitHub API
  • [yellow]RATE LIMITED[/yellow] - Using cached data due to rate limits
  • [yellow]DEMO[/yellow] - Using sample data in demo mode

๐Ÿ›ก๏ธ Error Handling

  • Retry Logic: Automatic retry with exponential backoff
  • Graceful Degradation: Falls back to cached data when API fails
  • Rate Limit Awareness: Detects and handles GitHub API rate limits
  • User Feedback: Clear error messages and status updates

๐Ÿ“– For detailed documentation, see LIVE_REFRESH.md

Project details

Verified details

These details have been verified by PyPI
Maintainers
Avatar for Gizmet from gravatar.com Gizmet

Unverified details

These details have not been verified by PyPI
Project links
Meta
  • License: MIT License (MIT)
  • Author: Gizmet
  • Maintainer: Gizmet
  • Tags github , terminal , heatmap , contributions , cli , rich
  • Requires: Python >=3.9
  • Provides-Extra: dev
Classifiers

Release history Release notifications | RSS feed

1.0.3

This version

1.0.2

1.0.1

1.0.0

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

gh_stats_heatmap-1.0.2.tar.gz (1.9 MB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

gh_stats_heatmap-1.0.2-py3-none-any.whl (36.9 kB view details)

Uploaded Python 3

File details

Details for the file gh_stats_heatmap-1.0.2.tar.gz.

File metadata

  • Download URL: gh_stats_heatmap-1.0.2.tar.gz
  • Upload date:
  • Size: 1.9 MB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/6.1.0 CPython/3.13.5

File hashes

Hashes for gh_stats_heatmap-1.0.2.tar.gz
Algorithm Hash digest
SHA256 3bc2e262128eba2068570152d9eeec9dec0e9e3ab8d05f55eddaede66f3db3ee
MD5 1ff13a8514d18dbd88e41dff2d7dd6e1
BLAKE2b-256 fa6d2137692594ba41e9856514639b965fbb8b5b29f5dead00612aa7dbf7d88f

See more details on using hashes here.

File details

Details for the file gh_stats_heatmap-1.0.2-py3-none-any.whl.

File metadata

File hashes

Hashes for gh_stats_heatmap-1.0.2-py3-none-any.whl
Algorithm Hash digest
SHA256 c37bbca91e28e0afa1831e8837fc85b15a6e6a45c591db49c3549bedf56ab8a6
MD5 ab408c17b8fda463969fb39d7bf3a07c
BLAKE2b-256 10d86a87286af639ee0d92a27f5bf443614b97a67363a87f762f7f89d170c63e

See more details on using hashes here.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page