GitHub Widget

A frameless desktop widget showing your GitHub contribution heatmap and recent commits. Sits on your desktop, resizable and draggable, with a system tray icon for show/hide. Works on Windows and Linux.

Features

• 26-week contribution heatmap with tooltips
• Today's contribution count, yearly total, streak counter
• Last 2 commits with repo, branch, SHA — click to open in browser
• Dark and Glassmorphism themes, persisted across restarts
• OAuth Device Flow auth — no PATs, no expiry
• Auto-refreshes every 10 minutes
• System tray icon — left-click or right-click → Show/Hide to restore after closing

Setup

Prerequisites

• Node.js 18+
• A GitHub OAuth App (free, one-time)

1. Create a GitHub OAuth App

1. Go to GitHub → Settings → Developer settings → OAuth Apps → New OAuth App
2. Fill in:
   • Application name: GitHub Widget
   • Homepage URL: https://github.com/epsilon003/github-widget
   • Authorization callback URL: https://github.com/epsilon003/github-widget (unused but required)
3. Check Enable Device Flow
4. Click Register application and copy the Client ID

2. Add your Client ID

Open renderer/app.js and replace:

const GITHUB_CLIENT_ID = 'YOUR_OAUTH_APP_CLIENT_ID';

The Client ID is public — safe to commit. No Client Secret needed for device flow.

3. Run

git clone https://github.com/epsilon003/github-widget
cd github-widget
npm install
npm start

On first launch, click Sign in with GitHub. Your browser opens to github.com/login/device — enter the code shown in the widget and authorize. Done.

Restoring the widget after hiding

Clicking the × hides the window — the app keeps running in the system tray. To bring it back:

• Left-click the green tray icon
• Or right-click the tray icon → Show / Hide

Themes

Switch between Dark and Glass using the pills in the widget footer or on the setup screen. The choice persists across restarts.

The Glass theme uses backdrop-filter: blur() for a frosted glass look — works best with a colorful wallpaper behind it.

Cutting a release

Releases are fully automated via GitHub Actions. To publish a new version:

# Bump the version in package.json first, then:
git add package.json
git commit -m "chore: bump version to 1.x.x"
git tag v1.x.x
git push origin main --tags

That's it. The release.yml workflow triggers on the tag, builds Windows (.exe) and Linux (.AppImage + .deb) binaries in parallel, auto-generates a changelog from commits since the last tag, and publishes everything to the GitHub Releases page. Pre-release tags like v1.0.0-beta.1 are automatically flagged as pre-release.

No secrets to configure — the workflow uses the built-in GITHUB_TOKEN that Actions provides automatically.

Project structure

github-widget/
├── main.js                      # Electron main process
├── preload.js                   # IPC context bridge
├── renderer/
│   ├── index.html               # Widget + setup screen markup
│   ├── style.css                # Dark + Glass themes
│   └── app.js                   # OAuth, API calls, render logic
├── .github/
│   ├── workflows/
│   │   ├── ci.yml               # Lint + validate on push/PR
│   │   └── release.yml          # Build + publish on tag
│   └── dependabot.yml           # Weekly dep updates
├── .gitignore
└── package.json

Config storage

• Windows: %APPDATA%\github-widget\config.json
• Linux: ~/.config/github-widget/config.json

Stores token, username, and theme preference. Delete to reset.

Auth

OAuth tokens don't expire on a schedule. They stay valid until revoked at GitHub → Settings → Applications. If revoked, the widget detects the 401 on next load and drops back to the sign-in screen automatically.