<p align="center">
<img src="image.png" alt="GitHub Stats Heatmap Logo" width="220"/>
</p>
<h1 align="center">🕵️♂️ GitHub Stats Heatmap</h1>
<p align="center">
<strong>Your GitHub activity, visualized — hacker style.</strong>
</p>
<p align="center">
<a href="https://pypi.org/project/gh-stats-heatmap/">
<img src="https://img.shields.io/pypi/v/gh-stats-heatmap?label=pypi&color=blue&style=flat" alt="PyPI">
</a>
<a href="https://img.shields.io/pypi/pyversions/gh-stats-heatmap?label=python&color=yellow&style=flat">
<img src="https://img.shields.io/pypi/pyversions/gh-stats-heatmap?label=python&color=yellow&style=flat" alt="Python versions">
</a>
<!--
<a href="https://pypi.org/project/gh-stats-heatmap/">
<img src="https://img.shields.io/pypi/dm/gh-stats-heatmap?label=downloads&color=purple&style=flat" alt="PyPI downloads">
</a>
-->
<a href="https://github.com/Gizmet/github-contribution-heatmap-viewer/blob/master/LICENSE">
<img src="https://img.shields.io/badge/license-MIT-gold?style=flat" alt="License: MIT">
</a>
<a href="https://github.com/Gizmet/github-contribution-heatmap-viewer/actions/workflows/ci.yml">
<img src="https://img.shields.io/github/actions/workflow/status/Gizmet/github-contribution-heatmap-viewer/ci.yml?branch=master&label=ci&logo=github&style=flat&color=brightgreen" alt="CI">
</a>
</p>
<p align="center">
<a href="#features">Features</a> •
<a href="#quick-start">Quick Start</a> •
<a href="#installation">Installation</a> •
<a href="#live-refresh-mode">Live Refresh</a> •
<a href="#plugin-system">Plugins</a> •
<a href="#roadmap">Roadmap</a> •
<a href="#contributing">Contributing</a> •
<a href="CHANGELOG.md">Changelog</a>
</p>
---
## ⚡ TL;DR
- **What:** Terminal-based GitHub contribution heatmap viewer
- **Why:** Instantly visualize your GitHub activity in your terminal, hacker style
- **How:**
```bash
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 ↓](#installation)
## 🆕 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
```bash
# Try it now!
ghstats yourusername --live
```
See the [Live Refresh Mode](#-live-refresh-mode) section for complete details.
---
## ✨ Features
<div align="center">
| 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 |
</div>
> **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
```bash
# 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)
```bash
# Install pipx if you don't have it
pip install pipx
pipx ensurepath
# Install ghstats
pipx install gh-stats-heatmap
```
### 🌍 PyPI Install
```bash
pip install gh-stats-heatmap
```
### 🍺 Homebrew Install (macOS/Linux)
```bash
# 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](https://github.com/Gizmet/homebrew-tap)
### 🔧 From Source
```bash
git clone https://github.com/Gizmet/github-contribution-heatmap-viewer
cd github-contribution-heatmap-viewer
pip install -e .
```
## 🎯 Usage Examples
<div align="center">
| 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) |
</div>
## 🔌 Plugin System
### Available Plugins
```bash
ghstats --list-plugins
```
### 🌍 Global Leaderboard Plugin
Shows top GitHub contributors worldwide using GraphQL API:
```bash
# 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:
```bash
# 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](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:
```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
```bash
# 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"**
```bash
# 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**
```bash
# Ensure token has correct scopes
ghstats username --token your_token_here
```
**Token not working**
```bash
# Verify token is valid
curl -H "Authorization: token your_token_here" https://api.github.com/user
```
## 🔧 Plugin Development
Extend functionality with custom plugins:
```python
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
<div align="center">
| 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 |
</div>
## 🏗️ 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
```bash
# 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](LICENSE) file for details.
## 🙏 Acknowledgments
- **Rich** - Beautiful terminal rendering
- **GitHub API** - Data source
- **Unicode** - For the glorious ░▒▓█ blocks
- **committers.top** - Inspiration for global leaderboards
---
<div align="center">
**Made with ❤️ for developers who live in the terminal**
⭐ **Star this repo if you find it useful!** ⭐
</div>
## ⚡ Live Refresh Mode
Experience real-time GitHub stats with auto-updating displays perfect for demos, monitoring, and live presentations:
```bash
# 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](LIVE_REFRESH.md)**
Raw data
{
"_id": null,
"home_page": "https://github.com/Gizmet/gh-stats-heatmap",
"name": "gh-stats-heatmap",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": "Gizmet <gizmet@example.com>",
"keywords": "github, terminal, heatmap, contributions, cli, rich",
"author": "Gizmet",
"author_email": "Gizmet <gizmet@example.com>",
"download_url": "https://files.pythonhosted.org/packages/cb/f6/bc2721ace89732f8f62faff2b91e1a7350b6c547cdd88d339bb47fc1165c/gh_stats_heatmap-1.0.3.tar.gz",
"platform": null,
"description": "<p align=\"center\">\n <img src=\"image.png\" alt=\"GitHub Stats Heatmap Logo\" width=\"220\"/>\n</p>\n\n<h1 align=\"center\">\ud83d\udd75\ufe0f\u200d\u2642\ufe0f GitHub Stats Heatmap</h1>\n<p align=\"center\">\n <strong>Your GitHub activity, visualized \u2014 hacker style.</strong>\n</p>\n\n<p align=\"center\">\n <a href=\"https://pypi.org/project/gh-stats-heatmap/\">\n <img src=\"https://img.shields.io/pypi/v/gh-stats-heatmap?label=pypi&color=blue&style=flat\" alt=\"PyPI\">\n </a>\n <a href=\"https://img.shields.io/pypi/pyversions/gh-stats-heatmap?label=python&color=yellow&style=flat\">\n <img src=\"https://img.shields.io/pypi/pyversions/gh-stats-heatmap?label=python&color=yellow&style=flat\" alt=\"Python versions\">\n </a>\n <!--\n <a href=\"https://pypi.org/project/gh-stats-heatmap/\">\n <img src=\"https://img.shields.io/pypi/dm/gh-stats-heatmap?label=downloads&color=purple&style=flat\" alt=\"PyPI downloads\">\n </a>\n -->\n <a href=\"https://github.com/Gizmet/github-contribution-heatmap-viewer/blob/master/LICENSE\">\n <img src=\"https://img.shields.io/badge/license-MIT-gold?style=flat\" alt=\"License: MIT\">\n </a>\n <a href=\"https://github.com/Gizmet/github-contribution-heatmap-viewer/actions/workflows/ci.yml\">\n <img src=\"https://img.shields.io/github/actions/workflow/status/Gizmet/github-contribution-heatmap-viewer/ci.yml?branch=master&label=ci&logo=github&style=flat&color=brightgreen\" alt=\"CI\">\n </a>\n</p>\n\n<p align=\"center\">\n <a href=\"#features\">Features</a> \u2022\n <a href=\"#quick-start\">Quick Start</a> \u2022\n <a href=\"#installation\">Installation</a> \u2022\n <a href=\"#live-refresh-mode\">Live Refresh</a> \u2022\n <a href=\"#plugin-system\">Plugins</a> \u2022\n <a href=\"#roadmap\">Roadmap</a> \u2022\n <a href=\"#contributing\">Contributing</a> \u2022\n <a href=\"CHANGELOG.md\">Changelog</a>\n</p>\n\n---\n\n## \u26a1 TL;DR\n\n- **What:** Terminal-based GitHub contribution heatmap viewer \n- **Why:** Instantly visualize your GitHub activity in your terminal, hacker style \n- **How:** \n ```bash\n pipx install gh-stats-heatmap\n gh-stats-heatmap\n ```\n- **Features:** Live refresh, plugin system, global leaderboards, themes, analytics, compare mode, and more!\n- **Platforms:** macOS, Linux, Windows\n\n[Get Started \u2193](#installation)\n\n## \ud83c\udd95 What's New\n\n### \ud83d\uddbc\ufe0f UI & Legend Improvements (v1.0.2)\n- **Legend is now a high-contrast Rich panel**: Instantly see what each block means, with clear colors and a plain-language explanation.\n- Improved accessibility and readability for all terminal themes.\n\n### \ud83c\udf89 Package Successfully Published! (v1.0.1)\nThe GitHub Stats Heatmap tool is now available on PyPI with easy installation methods!\n\n**Installation Options:**\n- \ud83d\ude80 **pipx** (Recommended): `pipx install gh-stats-heatmap`\n- \ud83c\udf0d **PyPI**: `pip install gh-stats-heatmap`\n- \ud83c\udf7a **Homebrew**: `brew tap gizmet/tap && brew install gizmet/tap/ghstats`\n\n### \u26a1 Live Refresh Mode\nExperience real-time GitHub stats with auto-updating displays! Perfect for demos, monitoring, and live presentations.\n\n**New Features:**\n- \ud83d\udd04 **Real-time Updates**: Auto-refresh every 30+ seconds\n- \ud83d\udee1\ufe0f **Rate Limit Protection**: Smart handling of GitHub API limits\n- \ud83c\udfad **Demo Mode**: Seamless fallback to realistic sample data\n- \ud83d\udcca **Status Indicators**: Clear visual feedback (LIVE/RATE LIMITED/DEMO)\n- \ud83d\udcbe **Data Caching**: Maintains display even when API is unavailable\n\n```bash\n# Try it now!\nghstats yourusername --live\n```\n\nSee the [Live Refresh Mode](#-live-refresh-mode) section for complete details.\n\n---\n\n## \u2728 Features\n\n<div align=\"center\">\n\n| Category | Features |\n|----------|----------|\n| **\ud83c\udfaf Core** | Zero-config heatmaps \u2022 Rich terminal output \u2022 Cross-platform |\n| **\ud83c\udfa8 Themes** | GitHub, dark, light, matrix, cyberpunk, monochrome \u2022 Custom JSON themes |\n| **\ud83d\uddbc\ufe0f UI** | **High-contrast, panel-based legend for easy interpretation** |\n| **\ud83d\udcca Analytics** | Streaks, trends, busiest month, activity patterns \u2022 Multiple sparklines \u2022 Advanced analytics \u2022 Smart insights |\n| **\ud83d\udd04 Compare** | Side-by-side user comparison \u2022 Per-user themes \u2022 Diff highlighting \u2022 Overlap analysis |\n| **\ud83c\udfc6 Leaderboards** | Repository/organization contributors \u2022 Global top contributors |\n| **\ud83d\udd0c Plugins** | Extensible plugin system \u2022 Global leaderboard plugin |\n| **\ud83c\udfae TUI** | Interactive terminal UI \u2022 Multiple views \u2022 Cell selection \u2022 Theme switching |\n| **\u26a1 Live** | Real-time refresh mode \u2022 Auto-updating displays \u2022 Rate limit protection \u2022 Demo mode \u2022 Smart caching |\n\n</div>\n\n> **Tip:** The heatmap legend is now always clear and easy to read, with high-contrast colors and a plain-language explanation\u2014perfect for all terminal backgrounds and accessibility needs.\n\n## \ud83d\ude80 Quick Start\n\n```bash\n# Install with pipx (easiest)\npipx install gh-stats-heatmap\n\n# Or install from PyPI\npip install gh-stats-heatmap\n\n# Instant visualization\nghstats yourusername\n\n# Compare two developers\nghstats user1 --compare user2\n\n# With global context\nghstats username --global-leaderboard --token YOUR_TOKEN\n\n# Live refresh for demos\nghstats username --live\n\n# Live refresh with custom interval\nghstats username --live --refresh-interval 60\n```\n\n## \ud83d\udce6 Installation\n\n### \ud83d\ude80 pipx Install (Recommended for CLI tools)\n```bash\n# Install pipx if you don't have it\npip install pipx\npipx ensurepath\n\n# Install ghstats\npipx install gh-stats-heatmap\n```\n\n### \ud83c\udf0d PyPI Install\n```bash\npip install gh-stats-heatmap\n```\n\n### \ud83c\udf7a Homebrew Install (macOS/Linux)\n```bash\n# Add the tap\nbrew tap gizmet/tap\n\n# Install ghstats\nbrew install gizmet/tap/ghstats\n```\n\nYou can also view and contribute to the Homebrew formula at: [https://github.com/Gizmet/homebrew-tap](https://github.com/Gizmet/homebrew-tap)\n\n### \ud83d\udd27 From Source\n```bash\ngit clone https://github.com/Gizmet/github-contribution-heatmap-viewer\ncd github-contribution-heatmap-viewer\npip install -e .\n```\n\n## \ud83c\udfaf Usage Examples\n\n<div align=\"center\">\n\n| Command | Result |\n|---------|--------|\n| `ghstats torvalds` | View Linus's contributions |\n| `ghstats gizmet --theme matrix` | Cyberpunk-style heatmap |\n| `ghstats user1 --compare user2` | Side-by-side comparison |\n| `ghstats user1 --compare user2 --theme dark --theme2 matrix` | Enhanced comparison with different themes |\n| `ghstats --plugin global-leaderboard` | Top GitHub contributors |\n| `ghstats username --tui` | Interactive TUI mode |\n| `ghstats username --live` | Real-time updates |\n| `ghstats username --live --refresh-interval 30` | Custom refresh interval |\n| `ghstats username --watch` | Watch mode (alias for --live) |\n\n</div>\n\n## \ud83d\udd0c Plugin System\n\n### Available Plugins\n```bash\nghstats --list-plugins\n```\n\n### \ud83c\udf0d Global Leaderboard Plugin\nShows top GitHub contributors worldwide using GraphQL API:\n\n```bash\n# Standalone plugin\nghstats --plugin global-leaderboard --token YOUR_TOKEN\n\n# Integrated with heatmap\nghstats username --global-leaderboard --token YOUR_TOKEN\n```\n\n**Features:**\n- \ud83d\udd04 **Resilient** - Retry logic, fallback data, network error handling\n- \ud83d\udcca **Rich Data** - Contributions, followers, rankings\n- \ud83c\udfa8 **Beautiful Output** - Formatted tables with proper alignment\n- \u26a1 **Fast** - Optimized GraphQL queries with pagination\n\n## \ud83c\udfae Interactive TUI Mode\n\nExperience your GitHub stats with an interactive terminal interface:\n\n```bash\n# Launch TUI mode\nghstats username --tui\n\n# TUI with custom theme\nghstats username --tui --theme matrix\n\n# TUI with API token\nghstats username --tui --token YOUR_TOKEN\n```\n\n**Features:**\n- **\ud83d\udcca Multiple Views**: Heatmap, stats, compare, and settings views\n- **\ud83c\udfaf Interactive Navigation**: Switch views and explore data\n- **\ud83c\udfa8 Theme Switching**: Change themes on the fly\n- **\ud83d\udcc8 Detailed Analytics**: Comprehensive statistics tables\n- **\ud83d\udd04 Data Refresh**: Reload data without restarting\n\n**Navigation:**\n- `h` = Heatmap view\n- `s` = Stats view \n- `v` = Compare view\n- `o` = Settings view\n- `t` = Change theme\n- `r` = Refresh data\n- `q` = Quit\n\nSee [TUI.md](TUI.md) for complete documentation.\n\n## \ud83c\udfa8 Themes\n\n### Built-in Themes\n- `github` - GitHub's official colors\n- `dark` - Dark terminal aesthetic\n- `light` - Light terminal friendly\n- `matrix` - Green terminal matrix vibe\n- `cyberpunk` - Neon magenta/yellow/cyan\n- `monochrome` - Clean black and white\n\n### Custom Themes\nCreate your own with JSON:\n\n```json\n{\n \"name\": \"My Theme\",\n \"colors\": [\"#ebedf0\", \"#9be9a8\", \"#40c463\", \"#30a14e\", \"#216e39\"]\n}\n```\n\n## \ud83d\udcc8 Sample Output\n\n```\n\u256d\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500 \ud83d\udd75\ufe0f\u200d\u2642\ufe0f GitHub Stats Heatmap \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u256e\n\u2502 \u2502\n\u2502 GitHub Contributions: torvalds (Past 52 Weeks) \u2502\n\u2502 \u2502\n\u2502 M \u2593\u2588\u2588\u2588\u2593\u2593\u2588\u2593\u2592\u2593\u2588\u2593\u2593\u2588\u2588\u2588\u2588\u2592\u2591\u2588\u2593\u2588\u2592\u2588\u2593\u2588\u2593\u2588\u2592\u2593\u2588\u2592\u2588\u2593\u2593\u2591\u2588\u2588\u2593\u2588\u2592\u2588\u2588\u2588\u2588\u2593\u2588\u2593\u2588\u2588\u2588\u2593 \u2502\n\u2502 T \u2588\u2593\u2592\u2592\u2592\u2592\u2591\u2592\u2588\u2588\u2592\u2592\u2592\u2593\u2592\u2592\u2592\u2588\u2588\u2591\u2593\u2593\u2592\u2592\u2593\u2592\u2588\u2588\u2593\u2592\u2592\u2592\u2592\u2592\u2592\u2588\u2588\u2593\u2593\u2592\u2593\u2593\u2593\u2591\u2588\u2588\u2592\u2593\u2593\u2592\u2592\u2591 \u2502\n\u2502 W \u2588\u2593\u2592\u2592\u2593\u2592\u2592\u2592\u2588\u2588\u2591\u2592\u2592\u2591\u2593\u2591\u2593\u2588\u2588\u2592\u2593\u2593\u2592\u2591\u2592\u2593\u2588\u2588\u2592\u2592\u2592\u2593\u2588\u2588\u2592\u2588\u2588\u2593\u2592\u2592\u2588\u2592\u2593\u2593\u2588\u2588\u2592\u2588\u2592\u2593\u2588\u2591 \u2502\n\u2502 T \u2593\u2591\u2592\u2593\u2591\u2593\u2588\u2593\u2588\u2588\u2593\u2592\u2593\u2592\u2592\u2593\u2593\u2588\u2588\u2592\u2592\u2593\u2591\u2592\u2592\u2591\u2588\u2588\u2592\u2592\u2592\u2588\u2593\u2593\u2592\u2588\u2588\u2592\u2588\u2588\u2593\u2593\u2588\u2592\u2588\u2588\u2592\u2588\u2593\u2593\u2592\u2591 \u2502\n\u2502 F \u2588\u2592\u2593\u2593\u2592\u2593\u2588\u2588\u2588\u2588\u2593\u2593\u2588\u2588\u2593\u2593\u2592\u2588\u2588\u2588\u2593\u2588\u2593\u2592\u2592\u2588\u2588\u2588\u2592\u2588\u2588\u2592\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2593\u2592\u2593\u2588\u2588\u2588\u2588\u2593\u2588\u2593\u2593\u2593\u2591 \u2502\n\u2502 S \u2588\u2588\u2588\u2588\u2593\u2593\u2588\u2593\u2593\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2593\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2593\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2593\u2588\u2588\u2588\u2591 \u2502\n\u2502 S \u2588\u2592\u2593\u2588\u2588\u2588\u2592\u2592\u2593\u2588\u2588\u2592\u2588\u2591\u2592\u2592\u2593\u2592\u2588\u2593\u2588\u2588\u2592\u2592\u2593\u2592\u2588\u2593\u2588\u2588\u2588\u2588\u2592\u2593\u2593\u2588\u2592\u2593\u2588\u2588\u2592\u2588\u2588\u2593\u2588\u2593\u2593\u2588\u2593\u2593\u2593\u2591 \u2502\n\u2502 \u2502\n\u2502 Weekly Activity: \u2584\u2582\u2582\u2582\u2582\u2582\u2583\u2581\u2586\u2585\u2583\u2582\u2582\u2582\u2582\u2582\u2582\u2587\u2584\u2582\u2582\u2583\u2581\u2582\u2582\u2582\u2587\u2584\u2582\u2582\u2582\u2582\u2583\u2583\u2582\u2588\u2585\u2582\u2583\u2583\u2582\u2582\u2583\u2582\u2587\u2584\u2582\u2583\u2582\u2582\u2582\u2581 \u2502\n\u2502 Monthly Trend: \u2581\u2581\u2581\u2581\u2588\u2582 \u2502\n\u2502 Consistency: \u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2583\u2581\u2581\u2581\u2581\u2581 \u2502\n\u2502 Trend: \ud83d\udcc8 Accelerating | Peak: This week (24 contributions) | Consistency: \u2705 Good (85%) \u2502\n\u2502 \u2502\n\u2502 Legend: \u2591 = 0 \u2592 = 1-3 \u2593 = 4-6 \u2588 = 7+ \u2502\n\u2502 \u2502\n\u2502 \u26a1 Current streak: 1 days | \ud83d\udcca Total contributions: 2885 | \ud83d\udcc5 Active days: 344/364 \u2502\n\u2502 (94.5%) | \ud83c\udfc6 Longest streak: 66 days | \ud83d\udcc8 This month: 170 | \ud83d\udcc9 Inactive weeks: 0 | \ud83d\udcc5 \u2502\n\u2502 Busiest week: 157 contributions (Week 36) | \ud83e\udd47 Most active weekday: S | \ud83c\udf1f Busiest \u2502\n\u2502 month: May | \ud83d\ude34 Least active weekday: T | \ud83d\udcc6 Avg/week: 55.5 | \ud83d\udcc8 Trend: Up (+241) \u2502\n\u2502 \u2502\n\u2502 \ud83c\udfaf Consistency: 85/100 | \u26a1 Pattern: Weekday focused (Monday peak, Tuesday low) \u2502\n\u2502 \ud83c\udf31 Seasonal: Strong Summer preference | \ud83d\ude80 Momentum: +25% | \ud83c\udf05 Weekend work: 15% \u2502\n\u2502 \u23f0 Peak hours: Early week focus (Monday peak) | \ud83d\ude34 Burnout risk: Low (healthy pace) \u2502\n\u2502 \ud83c\udfaf Improvement: High potential (few gaps) \u2502\n\u2502 \u2502\n\u2502 \ud83d\udcad You've contributed 2885 times in the last 52 weeks. Your consistency is excellent. \u2502\n\u2502 You're a weekday warrior. You show a strong summer preference. You're gaining momentum. \u2502\n\u2502 You prefer weekday work. You have great potential for growth. You're on a 1-day streak \u2502\n\u2502 with increasing activity. \u2502\n\u2502 \u2502\n\u2502 \ud83c\udf0d Global GitHub Contributors \u2502\n\u2502 \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u252c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u252c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u252c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u252c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510 \u2502\n\u2502 \u2502 Rank \u2502 User \u2502 Name \u2502 Contributions \u2502 Followers \u2502 \u2502\n\u2502 \u251c\u2500\u2500\u2500\u2500\u2500\u2500\u253c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u253c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u253c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u253c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2524 \u2502\n\u2502 \u2502 1 \u2502 @Charles-Chrismann \u2502 Charles Chrismann \u2502 12,290 \u2502 16,017 \u2502 \u2502\n\u2502 \u2502 2 \u2502 @lllyasviel \u2502 lllyasviel \u2502 9,121 \u2502 19,979 \u2502 \u2502\n\u2502 \u2502 3 \u2502 @phodal \u2502 Fengda Huang \u2502 9,052 \u2502 20,351 \u2502 \u2502\n\u2502 \u2502 4 \u2502 @skydoves \u2502 Jaewoong Eum \u2502 7,045 \u2502 12,058 \u2502 \u2502\n\u2502 \u2502 5 \u2502 @jeresig \u2502 John Resig \u2502 6,066 \u2502 18,881 \u2502 \u2502\n\u2502 \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518 \u2502\n\u2502 \u2502\n\u2570\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u256f\n```\n\n## \ud83d\udee0\ufe0f API Tokens\n\n### \ud83d\udd11 When You Need GitHub API Tokens\n\n**Required for:**\n- \ud83d\udd12 **Private repository data** - Access to private repo contributions\n- \ud83c\udfc6 **Repository leaderboards** - Top contributors in specific repos\n- \ud83c\udfe2 **Organization leaderboards** - Contributors within organizations\n- \ud83c\udf0d **Global leaderboard plugin** - Worldwide top GitHub contributors\n- \ud83d\udcca **Integrated global leaderboard** - Combined heatmap + leaderboard\n- \ud83d\udd0d **Higher rate limits** - 5000 requests/hour vs 60 requests/hour\n\n**Not required for:**\n- \u2705 **Public profile heatmaps** - Basic contribution visualization\n- \u2705 **Public user statistics** - Streaks, trends, patterns\n- \u2705 **Compare mode** - Side-by-side public user comparison\n- \u2705 **Theme customization** - All theme features\n- \u2705 **Live refresh mode** - Auto-updating displays (with rate limits)\n\n### \ud83d\ude80 Creating a GitHub API Token\n\n1. **Go to GitHub Settings**: https://github.com/settings/tokens\n2. **Click \"Generate new token\"** \u2192 \"Generate new token (classic)\"\n3. **Set token name**: e.g., \"ghstats-cli\"\n4. **Select scopes**:\n - \u2705 `public_repo` (for public repository data)\n - \u2705 `read:org` (for organization leaderboards)\n - \u2705 `read:user` (for user profile data)\n5. **Click \"Generate token\"**\n6. **Copy the token** (store it securely - you won't see it again!)\n\n### \ud83d\udcbb Using Your Token\n\n```bash\n# Set as environment variable (recommended)\nexport GITHUB_TOKEN=your_token_here\nghstats username\n\n# Or pass directly via command line\nghstats username --token your_token_here\n\n# For global leaderboard\nghstats --plugin global-leaderboard --token your_token_here\n\n# Combined heatmap + leaderboard\nghstats username --global-leaderboard --token your_token_here\n```\n\n### \ud83d\udd12 Security Best Practices\n\n- **Never commit tokens** to version control\n- **Use environment variables** instead of command line arguments\n- **Set minimal permissions** - only grant necessary scopes\n- **Rotate tokens regularly** - regenerate every 90 days\n- **Use different tokens** for different applications\n\n### \ud83d\udcca Rate Limits\n\n| Authentication | Rate Limit | Use Case |\n|----------------|------------|----------|\n| **None** | 60 requests/hour | Basic public profiles |\n| **Token** | 5000 requests/hour | Full features, private repos |\n\n### \ud83d\udee0\ufe0f Troubleshooting\n\n**\"API rate limit exceeded\"**\n```bash\n# Check your rate limit status\nghstats username --token your_token_here\n\n# Wait for reset or use demo mode\nghstats username --live # Automatically uses demo mode when rate limited\n```\n\n**\"Not found\" for private repos**\n```bash\n# Ensure token has correct scopes\nghstats username --token your_token_here\n```\n\n**Token not working**\n```bash\n# Verify token is valid\ncurl -H \"Authorization: token your_token_here\" https://api.github.com/user\n```\n\n## \ud83d\udd27 Plugin Development\n\nExtend functionality with custom plugins:\n\n```python\nfrom plugins.base import GhStatsPlugin\n\nclass MyPlugin(GhStatsPlugin):\n def name(self) -> str:\n return \"my-plugin\"\n \n def description(self) -> str:\n return \"My custom plugin\"\n \n def requires_token(self) -> bool:\n return False\n \n def execute(self, **kwargs) -> Dict[str, Any]:\n # Your plugin logic here\n return {\"success\": True, \"data\": \"...\"}\n```\n\n## \ud83d\udccb Roadmap\n\n<div align=\"center\">\n\n| Status | Feature | Description |\n|--------|---------|-------------|\n| \u2705 **Complete** | Core heatmap rendering | Beautiful terminal output with Unicode blocks |\n| \u2705 **Complete** | Theme system | Built-in + custom JSON themes |\n| \u2705 **Complete** | Statistics engine | Streaks, trends, patterns, analytics |\n| \u2705 **Complete** | Compare mode | Side-by-side user comparison |\n| \u2705 **Complete** | Plugin architecture | Extensible plugin system |\n| \u2705 **Complete** | Global leaderboard | Top GitHub contributors worldwide |\n| \u2705 **Complete** | Live refresh | Real-time updates |\n| \ud83d\udd04 **In Progress** | Export features | PNG, HTML, JSON export |\n| \ud83d\udd04 **In Progress** | TUI mode | Interactive terminal UI |\n| \ud83d\udccb **Planned** | Team analytics | Organization insights |\n| \ud83d\udccb **Planned** | Historical trends | Year-over-year comparisons |\n| \ud83d\udccb **Planned** | Custom metrics | User-defined contribution types |\n\n</div>\n\n## \ud83c\udfd7\ufe0f Project Structure\n\n```\ngithub-contribution-heatmap-viewer/\n\u251c\u2500\u2500 ghstats.py # CLI entry point\n\u251c\u2500\u2500 github_api.py # GitHub API integration\n\u251c\u2500\u2500 heatmap.py # Grid generation logic\n\u251c\u2500\u2500 render.py # Rich terminal rendering\n\u251c\u2500\u2500 utils.py # Utility functions\n\u251c\u2500\u2500 plugins/ # Plugin system\n\u2502 \u251c\u2500\u2500 __init__.py # Plugin manager\n\u2502 \u251c\u2500\u2500 base.py # Base plugin class\n\u2502 \u2514\u2500\u2500 global_leaderboard.py # Global leaderboard plugin\n\u251c\u2500\u2500 tests/ # Test suite\n\u251c\u2500\u2500 themes/ # Theme definitions\n\u2514\u2500\u2500 README.md # This file\n```\n\n## \ud83e\uddea Development\n\n```bash\n# Install in development mode\npip install -e .\n\n# Run tests\npytest\n\n# Run with coverage\npytest --cov=.\n\n# Format code\nblack .\n\n# Lint code\nflake8 .\n```\n\n## \ud83e\udd1d Contributing\n\nWe welcome contributions! Here's how:\n\n1. **\ud83c\udf74 Fork** the repository\n2. **\ud83c\udf31 Create** a feature branch: `git checkout -b feature/amazing-thing`\n3. **\ud83d\udca5 Commit** your changes: `git commit -m 'Add amazing thing'`\n4. **\ud83d\ude80 Push** to the branch: `git push origin feature/amazing-thing`\n5. **\ud83d\udcec Open** a Pull Request\n\n**Guidelines:**\n- Follow PEP 8 style guidelines\n- Add tests for new functionality\n- Update documentation for new features\n- Write clear commit messages\n\n## \ud83d\udcc4 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## \ud83d\ude4f Acknowledgments\n\n- **Rich** - Beautiful terminal rendering\n- **GitHub API** - Data source\n- **Unicode** - For the glorious \u2591\u2592\u2593\u2588 blocks\n- **committers.top** - Inspiration for global leaderboards\n\n---\n\n<div align=\"center\">\n\n**Made with \u2764\ufe0f for developers who live in the terminal**\n\n\u2b50 **Star this repo if you find it useful!** \u2b50\n\n</div> \n\n## \u26a1 Live Refresh Mode\n\nExperience real-time GitHub stats with auto-updating displays perfect for demos, monitoring, and live presentations:\n\n```bash\n# Basic live refresh (30s minimum interval)\nghstats username --live\n\n# Custom refresh interval\nghstats username --live --refresh-interval 60\n\n# Watch mode (alias for --live)\nghstats username --watch\n\n# Live refresh with compare mode\nghstats username --compare user2 --live\n\n# Live refresh with custom theme\nghstats username --live --theme matrix\n```\n\n### \ud83c\udfaf Live Refresh Features\n\n- **\ud83d\udd04 Auto-Updating**: Real-time data refresh with customizable intervals\n- **\ud83d\udee1\ufe0f Rate Limit Protection**: Automatic detection and graceful handling of GitHub API rate limits\n- **\ud83c\udfad Demo Mode**: Seamless fallback to realistic sample data when rate limited\n- **\ud83d\udcca Status Indicators**: Clear visual feedback (LIVE/RATE LIMITED/DEMO)\n- **\ud83d\udcbe Data Caching**: Uses cached data when API calls fail\n- **\u23f0 Smart Intervals**: Minimum 30-second intervals to prevent rate limiting\n- **\ud83c\udfa8 Theme Support**: Full theme compatibility in live mode\n- **\ud83d\udd04 Compare Mode**: Side-by-side live comparison of multiple users\n\n### \ud83c\udfad Demo Mode\n\nWhen rate limited, the live refresh automatically switches to demo mode:\n\n- **Realistic Data**: Generates authentic-looking contribution patterns\n- **Weekday Patterns**: Higher activity on weekdays, lower on weekends\n- **Random Variation**: Natural-looking contribution counts and patterns\n- **Seamless Transition**: No interruption to the live display\n\n### \ud83d\udcca Status Display\n\nLive refresh provides comprehensive status information:\n\n```\nLast update: 14:30:25 | Updates: 15 | Status: LIVE | Next refresh in 60s\nRate limit: 4850/5000 requests remaining | Reset at 15:00:00\n```\n\n**Status Types:**\n- `[green]LIVE[/green]` - Real-time data from GitHub API\n- `[yellow]RATE LIMITED[/yellow]` - Using cached data due to rate limits\n- `[yellow]DEMO[/yellow]` - Using sample data in demo mode\n\n### \ud83d\udee1\ufe0f Error Handling\n\n- **Retry Logic**: Automatic retry with exponential backoff\n- **Graceful Degradation**: Falls back to cached data when API fails\n- **Rate Limit Awareness**: Detects and handles GitHub API rate limits\n- **User Feedback**: Clear error messages and status updates\n\n\ud83d\udcd6 **For detailed documentation, see [LIVE_REFRESH.md](LIVE_REFRESH.md)** \n",
"bugtrack_url": null,
"license": "MIT",
"summary": "GitHub Contribution Graph in your terminal \u2014 for hackers who prefer Unicode over UI",
"version": "1.0.3",
"project_urls": {
"Bug Tracker": "https://github.com/Gizmet/github-contribution-heatmap-viewer/issues",
"Documentation": "https://github.com/Gizmet/github-contribution-heatmap-viewer#readme",
"Homepage": "https://github.com/Gizmet/github-contribution-heatmap-viewer",
"Repository": "https://github.com/Gizmet/github-contribution-heatmap-viewer"
},
"split_keywords": [
"github",
" terminal",
" heatmap",
" contributions",
" cli",
" rich"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "5403a1d18420dcc2c0845a1a562f8da11a7dfe02fbcc06eeeb7bc7ab9c03fcfb",
"md5": "e38c36f321176c49824816be80105900",
"sha256": "29166cda2a780768adc11dfee35740b0f7aa31ab381efe44df507a965298d634"
},
"downloads": -1,
"filename": "gh_stats_heatmap-1.0.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "e38c36f321176c49824816be80105900",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 36886,
"upload_time": "2025-07-14T04:06:08",
"upload_time_iso_8601": "2025-07-14T04:06:08.136419Z",
"url": "https://files.pythonhosted.org/packages/54/03/a1d18420dcc2c0845a1a562f8da11a7dfe02fbcc06eeeb7bc7ab9c03fcfb/gh_stats_heatmap-1.0.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "cbf6bc2721ace89732f8f62faff2b91e1a7350b6c547cdd88d339bb47fc1165c",
"md5": "6330ac48da4333c71dbb7fdb051cdbd0",
"sha256": "96b49ad29b2398cd8de21ca2006e0aa251a9551acf70fcb2ea851a46e7f411e3"
},
"downloads": -1,
"filename": "gh_stats_heatmap-1.0.3.tar.gz",
"has_sig": false,
"md5_digest": "6330ac48da4333c71dbb7fdb051cdbd0",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 1874813,
"upload_time": "2025-07-14T04:06:17",
"upload_time_iso_8601": "2025-07-14T04:06:17.402429Z",
"url": "https://files.pythonhosted.org/packages/cb/f6/bc2721ace89732f8f62faff2b91e1a7350b6c547cdd88d339bb47fc1165c/gh_stats_heatmap-1.0.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-14 04:06:17",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Gizmet",
"github_project": "gh-stats-heatmap",
"github_not_found": true,
"lcname": "gh-stats-heatmap"
}
JSON
