🎯 GitHub Contributions Tracker

A minimal, beautiful desktop app to track your GitHub contributions in real-time

✨ Features

• 🎨 Beautiful Visual Display - GitHub-style contribution graph right on your desktop
• 🌙 Dark/Light Themes - Switch between themes to match your preference
• 🔧 Minimal Configuration - Just add your GitHub username and token
• 📱 Always Accessible - System tray integration for quick access
• 🖱️ Draggable Window - Position it anywhere on your screen
• 💾 Persistent Settings - Your preferences are saved automatically
• 🌐 Offline Detection - Smart handling of online/offline states
• 🔄 Real-time Updates - Fetches the latest contribution data

🚀 Quick Start

Installation

Download Pre-built Binaries

1. Go to the Releases page
2. Download the appropriate version for your system:
   • Linux: .deb or .AppImage

Build from Source

# Clone the repository
git clone https://github.com/mohammad-hassani/github-contributions.git
cd github-contributions

# Install dependencies
npm install

# Run the application
npm start

Initial Setup

1. Right-click on the app window and select "Settings"
2. Enter your GitHub username
3. Create a GitHub Personal Access Token:
   • Go to GitHub Settings > Developer settings > Personal access tokens
   • Click "Generate new token (classic)"
   • No scopes needed - just create a simple token
   • Copy and paste the token into the app
4. Choose your preferred theme (Light/Dark)
5. Click Save

📸 Screenshots

The app displays your contribution graph in a compact, draggable window.

🎮 Usage

Basic Controls

• Right-click anywhere on the app to open the context menu
• Left-click and drag to move the window around
• System tray icon - Click to show/hide the app
• Settings panel - Configure username, token, and theme

Context Menu Options

• Open - Show and focus the app window
• Settings - Open the configuration panel
• Close - Exit the application

🛠️ Development

Prerequisites

• Node.js (v16 or higher)
• npm or yarn

Setup

# Clone the repository
git clone https://github.com/mohammad-hassani/github-contributions.git
cd github-contributions

# Install dependencies
npm install

# Run in development mode
npm start

Building for Distribution

# Build for Linux
npm run build

# Build specific formats
npm run build:deb        # Linux .deb package
npm run build:appimage   # Linux .AppImage
npm run release          # Build and publish to GitHub

Project Structure

github-contributions/
├── main.js              # Electron main process
├── renderer.js          # Frontend logic and API calls
├── index.html           # UI structure and styling
├── icon.png             # Application icon
├── package.json         # Dependencies and build config
└── README.md           # This file

🔧 Configuration

GitHub Token Setup

The app requires a GitHub Personal Access Token for API access:

1. Visit GitHub Settings > Tokens
2. Click "Generate new token (classic)"
3. Give it a descriptive name (e.g., "Contributions Tracker")
4. No scopes required - the app only needs public access
5. Click "Generate token"
6. Copy the token and paste it in the app settings

Settings Storage

• Settings are stored locally using localStorage
• Window position and size are automatically saved
• All data remains on your local machine

🐛 Troubleshooting

Common Issues

Q: App shows "No contribution data found"

• Verify your GitHub username is correct
• Ensure your token is valid and not expired
• Check your internet connection

Q: App window disappears

• Check the system tray for the app icon
• Right-click the tray icon and select "Open"

Q: Token authentication fails

• Generate a new token from GitHub settings
• Ensure no extra spaces when pasting the token
• Verify the token hasn't expired

Q: App won't start

• Try running with --no-sandbox flag: electron . --no-sandbox
• Ensure you have proper display server permissions (Linux)
• Check that Node.js and Electron dependencies are properly installed

Debug Mode

To enable debug logging:

1. Open developer tools with F12 (if enabled)
2. Check the browser console for API responses and errors

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Development Workflow

1. Fork the repository
2. Create a feature branch: git checkout -b feature-name
3. Make your changes and test thoroughly
4. Commit your changes: git commit -m 'Add some feature'
5. Push to the branch: git push origin feature-name
6. Open a Pull Request

Areas for Improvement

• Add contribution streak counter
• Support for multiple GitHub accounts
• Customizable color themes
• Export contribution data
• Notification for new contributions
• Integration with GitHub Actions

📄 License

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

🙏 Acknowledgments

• Electron - Cross-platform desktop app framework
• GitHub GraphQL API - For fetching contribution data
• The open-source community for inspiration and tools

📞 Support

If you encounter any issues or have suggestions:

• 🐛 Report a bug
• 💡 Request a feature
• 📧 Email: hasani9821.mh@gmail.com

---

Made with ❤️ by Mohammad Hassani

⭐ Star this repo if it helped you track your GitHub journey!