🔍 GitGlyph

Real-time GitHub Intelligence Dashboard - Monitor GitHub activity with style and efficiency

📋 Overview

GitGlyph is a powerful, real-time terminal-based dashboard that provides intelligent monitoring of GitHub activities. Track users, repositories, and organizations with customizable notifications and filtering capabilities, all within an elegant TUI (Terminal User Interface).

✨ Features

🎯 Core Functionality

• Real-time Monitoring - Live updates of GitHub events with configurable polling intervals
• Multi-target Support - Monitor users, repositories, and organizations simultaneously
• Smart Filtering - Filter events by type, actor, or repository name
• Hot Reloading - Dynamically reload configuration without restarting the application

🔔 Notification System

• Desktop Notifications - Get alerts for specific event types
• Customizable Rules - Configure notifications per repository
• Event Type Support - Monitor Issues, Pull Requests, Releases, and more

🎨 User Interface

• Modern TUI - Built with Textual for a responsive terminal experience
• Color-coded Events - Easy visual distinction between different event types
• Interactive Controls - Keyboard shortcuts for enhanced productivity
• Rate Limit Monitoring - Real-time API usage tracking

🚀 Quick Start

Prerequisites

• Python 3.8 or higher
• GitHub Personal Access Token
• Terminal with color support

Installation

1. Clone the repository

   git clone https://github.com/LMLK-Seal/git-glyph.git
   cd git-glyph

2. Install dependencies

   pip install -r requirements.txt

3. Add the token to your .env file:

   GITHUB_TOKEN=ghp_your_token_here
   

4. Configure monitoring targets

   # Edit config.toml to add users, repos, and organizations
   nano config.toml

5. Run GitGlyph

   python gitglyph.py

⚙️ Configuration

GitGlyph uses a config.toml file for configuration:

# Polling interval in seconds (be mindful of API limits)
poll_interval = 15

# GitHub users to monitor
users = [
    "torvalds",
    "gvanrossum"
]

# Repositories with optional notification rules
[[repos]]
name = "facebook/react"
notify_on = ["ReleaseEvent"]

[[repos]]
name = "tldraw/tldraw"
notify_on = ["IssuesEvent", "ReleaseEvent"]

# Organizations (use with caution - can be very noisy)
# orgs = ["google"]

🔧 Configuration Options

Option	Type	Description
poll_interval	Integer	Seconds between API calls (default: 15)
users	Array	GitHub usernames to monitor
repos	Array of Tables	Repositories with optional notification rules
orgs	Array	Organizations to monitor (optional)

🔔 Notification Events

Supported event types for notifications:

• IssuesEvent - Issue created, closed, or updated
• PushEvent - Code pushed to repository
• PullRequestEvent - Pull request actions
• ReleaseEvent - New releases
• WatchEvent - Repository starred
• ForkEvent - Repository forked
• CreateEvent - Branch or tag created

🎮 Keyboard Controls

Key	Action	Description
f	Toggle Filter	Enable/disable event filtering
r	Reload Config	Hot reload configuration file
q	Quit	Exit the application

🔐 Authentication

GitGlyph requires a GitHub Personal Access Token for API access:

1. Go to GitHub Settings > Developer settings > Personal access tokens
2. Generate a new token with repo and user scopes
3. Add the token to your .env file:

   GITHUB_TOKEN=ghp_your_token_here
   

📊 Event Types Supported

GitGlyph intelligently parses and displays various GitHub events:

• 📝 Push Events - Commit information and branch details
• 🐛 Issue Events - Issue creation, updates, and closures
• 🔀 Pull Request Events - PR lifecycle management
• 🏷️ Release Events - New version releases
• ⭐ Watch Events - Repository stars and follows
• 🍴 Fork Events - Repository forks
• ➕ Create Events - New branches and tags

🚨 Rate Limiting

GitGlyph respects GitHub's API rate limits:

• Authenticated requests: 5,000 per hour
• Real-time monitoring: Shows remaining quota
• Smart polling: Uses ETags to minimize API calls

⚠️ Tip: Avoid setting poll_interval too low to conserve API quota

🛠️ Dependencies

httpx>=0.24.0      # HTTP client for API requests
tomli>=2.0.0       # TOML configuration parsing
python-dotenv>=1.0.0  # Environment variable loading
textual>=0.32.0    # Terminal User Interface
plyer>=2.1.0       # Cross-platform notifications

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

📝 License

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

🙏 Acknowledgments

• Built with Textual for the amazing TUI framework
• Inspired by the need for real-time GitHub monitoring
• Thanks to the GitHub API for providing comprehensive event data

📞 Support

If you encounter any issues or have questions:

1. Create a new issue with detailed information
2. Include your configuration (without sensitive tokens)

---

⭐ Star this repository if GitGlyph helps you stay on top of GitHub activity!

Made with ❤️ for the developer community