Skip to content

README.md

Latest commit

 

History

History
227 lines (158 loc) · 6.68 KB

README.md

File metadata and controls

227 lines (158 loc) · 6.68 KB

🎯 GitHub Contributions Tracker

GitHub Contributions Electron License Platform

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

Download

✨ 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:
  4. Choose your preferred theme (Light/Dark)
  5. Click Save

📸 Screenshots

App Icon

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:

Made with ❤️ by Mohammad Hassani

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