Ahmed x86 - gh-radar for Waybar 📡

✨ Key Features

• Animated Ticker: Waybar text changes dynamically when a new push occurs. It shows the branch and commit message, then the repository name, and finally returns to your username.
• Audio Alerts: Plays a retro notification sound instantly upon detecting a new push.
• Avatar Notifications: Sends a native desktop notification containing the committer's actual GitHub avatar and commit details.
• Interactive Buttons: Left-click to open your GitHub profile, Right-click to open notifications directly from Waybar.
• Manual Refresh (New!): Middle-click the module to instantly fetch the latest updates using Linux signals (SIGUSR1).
• Smart Resource Management: Dynamic polling intervals (10s when active, 60s when idle) or a complete Sleep Mode (-t 0) to save battery and bandwidth.
• Custom Icons (New!): Choose from 10 different Nerd Font icons (Octocat, Git branch, etc.) using the -icon argument.
• API Optimized: Uses GitHub's ETag headers to respect API rate limits.

🛠️ Installation & Setup

1. Clone & Copy Files

git clone https://github.com/ahmed-x86/gh-radar.git
cd gh-radar

# Copy sound to your config
cp -r sounds ~/.config/

# Setup Waybar scripts directory
mkdir -p ~/.config/waybar/scripts
cp github_radar.py ~/.config/waybar/scripts/
chmod +x ~/.config/waybar/scripts/github_radar.py

2. Add Your Credentials (.env)

Create a .env file to authenticate with GitHub:

nano ~/.config/waybar/scripts/.env

Add the following (replace with your info):

GITHUB_USERNAME=your_github_username
GITHUB_PAT=your_personal_access_token_here

3. Install Dependencies

Depending on your Linux distribution, install the required Python libraries. You also need an audio player (mpv or paplay) and a notification daemon (libnotify).

For Arch Linux / Manjaro:

sudo pacman -S python-requests python-dotenv

For Ubuntu / Debian (or using pip):

pip install requests python-dotenv

⚙️ Usage & Arguments

The script supports arguments to customize its behavior:

• my_repos_only: Only triggers alerts for repositories you own (ignores activity from other repos you watch/star).
• -t 0: Manual Mode. The script will not poll GitHub automatically. It will sleep completely until you middle-click the Waybar module.
• -icon <1-10>: (New!) Choose the icon displayed in Waybar. Choose a number from 1 to 10 (e.g., -icon 2 for the Octocat).

# Examples:
github_radar.py                    # Tracks everything, dynamic polling, default icon
github_radar.py my_repos_only -icon 2 # Tracks only your repos, uses Octocat icon
github_radar.py -t 0               # Tracks everything, manual refresh ONLY
github_radar.py my_repos_only -t 0 -icon 5 # Tracks only your repos, manual refresh ONLY, Git logo

🖥️ Waybar Configuration

1. Module Configuration (config.jsonc)

💡 Pro Tip: Add "reload_style_on_change": true, at the very top of your Waybar config file. This allows Waybar to instantly apply changes when you edit the config or style files without needing a manual restart!

Add this module to your Waybar config file (under modules-left, modules-center, or modules-right):

"custom/github-radar": {
    "format": "{}",
    "return-type": "json",
    "exec": "~/.config/waybar/scripts/github_radar.py my_repos_only -t 0 -icon 2", // Customize args here!
    "on-click": "xdg-open https://github.com/ahmed-x86",
    "on-click-right": "xdg-open https://github.com/notifications",
    "on-click-middle": "pkill -USR1 -f github_radar.py", // Sends the refresh signal
    "restart-interval": 0 // Set to 0 because the script runs its own background loop
}

(Note: Change ahmed-x86 to your actual GitHub username in the on-click URL).

2. Styling (style.css)

Choose the theme that matches your current Waybar setup and add it to your style.css.

/* GitHub Radar - Default Theme */
#custom-github-radar {
    background-color: #24292e; /* Dark GitHub background */
    color: #ffffff;
    border-radius: 10px;
    padding: 0px 10px;
    margin: 4px 5px;
    font-weight: bold;
    border: 1px solid #444c56;
    transition: all 0.3s ease;
}

#custom-github-radar:hover {
    background-color: #2ea043; /* GitHub green */
    color: #ffffff;
    border-color: #2ea043;
}

/* GitHub Radar - Catppuccin Mocha Theme */
#custom-github-radar {
    background-color: #1e1e2e; /* Base */
    color: #cdd6f4; /* Text */
    border-radius: 10px;
    padding: 0px 10px;
    margin: 4px 5px;
    font-weight: bold;
    border: 1px solid #313244; /* Surface0 */
    transition: all 0.3s ease;
}

#custom-github-radar:hover {
    background-color: #a6e3a1; /* Green */
    color: #11111b; /* Crust for contrast */
    border-color: #a6e3a1;
}

/* GitHub Radar - Dracula Theme */
#custom-github-radar {
    background-color: #282a36; /* Background */
    color: #f8f8f2; /* Foreground */
    border-radius: 10px;
    padding: 0px 10px;
    margin: 4px 5px;
    font-weight: bold;
    border: 1px solid #44475a; /* Selection */
    transition: all 0.3s ease;
}

#custom-github-radar:hover {
    background-color: #50fa7b; /* Green */
    color: #282a36; /* Background for contrast */
    border-color: #50fa7b;
}