azaan-widget

azaan-widget

A macOS-style desktop widget for Linux (GNOME) that shows Islamic prayer times right on your wallpaper. It sits in the desktop layer — beneath your app windows, sticky across workspaces, locked in a corner — exactly like a macOS desktop widget. Prayer data comes from the excellent azaan CLI.

┌──────────────────────┐
│  KARACHI             │
│  Asr                 │   ← next prayer (hero)
│  5:13 PM · in 4h 28m │
│  ──────────────────  │
│  🌅  Fajr     4:13 AM │
│  ☀  Sunrise  5:41 AM │
│  🌞  Dhuhr   12:31 PM │   ← current prayer highlighted
│  🌤  Asr      5:13 PM │
│  🌇  Maghrib  7:20 PM │
│  🌙  Isha     8:49 PM │
│  ──────────────────  │
│  22 Dhū al-Ḥijjah    │
└──────────────────────┘

Two modes

Mode	Feel	How
GNOME extension (recommended on GNOME)	Truly part of the desktop, like an icon — slides with workspace switches, never in the overview or alt-tab. Drag it anywhere.	azaan-widget enable-extension
Standalone window (any X11/XWayland)	A GTK window kept beneath your windows. Works outside GNOME, but behaves like a window in the overview/alt-tab.	azaan-widget install

Recommended: GNOME Shell extension

npm install -g azaan-widget
azaan-widget enable-extension
# then log out and back in (Wayland can't hot-load a new extension)

After login the widget sits on your desktop and behaves like a desktop icon: click and drag anywhere on the card to move it; it locks where you drop it and remembers the spot. It lives just above the wallpaper (and your desktop icons) and below every window, slides along during workspace switches exactly like the icons do, and never shows up in the overview, alt-tab, or window animations.

Remove it with azaan-widget disable-extension.

Standalone window

npx azaan-widget                 # run once
npm install -g azaan-widget
azaan-widget install             # autostart on login

Press Super+D (show desktop) to reveal it when windows cover it.

Requirements

• Linux with GNOME (X11 or Wayland via XWayland)
• Node.js ≥ 16
• Python 3 with GTK 3 / PyGObject

Install the Python/GTK bits if needed:

# Debian / Ubuntu
sudo apt install python3-gi gir1.2-gtk-3.0

# Fedora
sudo dnf install python3-gobject gtk3

# Arch
sudo pacman -S python-gobject gtk3

Then check everything is in place:

azaan-widget doctor

Usage

azaan-widget [command] [options]

Command	Description
start	Launch the widget (default), pinned to the desktop
stop	Stop the running widget
restart	Reload the widget
status	Show running / autostart status
install	Enable autostart on login
uninstall	Disable autostart and stop the widget
doctor	Check prerequisites (Python, GTK, azaan)
help	Show help

Options

• --corner <pos> — top-right (default), top-left, bottom-right, bottom-left
• --layer <mode> — below (default) or desktop (see below)
• --foreground — run without detaching (handy for debugging)

azaan-widget start --corner bottom-left
azaan-widget install --corner top-left

Moving the widget

• GNOME extension: click and drag anywhere on the card, like a desktop icon. It locks where you release and remembers the spot. (The ⠿ in the top-right is just a visual hint that the card is movable.)
• Standalone window: press and drag the ⠿ handle in the top-right corner, release to lock.

To reset to the default corner, delete ~/.config/azaan-widget/ext-position.json (extension) or ~/.config/azaan-widget/position.json (standalone).

Layer modes (--layer)

Mode	Behaviour
below (default)	Sits beneath your app windows (covered by them, revealed on Super+D), sticky across workspaces, and draggable via the handle.
desktop	A true _NET_WM_WINDOW_TYPE_DESKTOP window fused into the wallpaper. The most "part of the desktop" feel, but not draggable — most compositors route clicks through to the desktop. Position it with --corner instead.

azaan-widget start --layer desktop --corner top-left

Setting your location

The widget shows whatever location the azaan CLI is configured with. Set it once:

npx azaan config --city "Cairo" --country "Egypt"
# or by coordinates
npx azaan config --lat 30.0444 --lon 31.2357

Then azaan-widget restart.

How it works

• The widget is a small Python + GTK 3 app (src/azaan_widget.py) rendered as a _NET_WM_WINDOW_TYPE_DESKTOP window, so the window manager treats it as part of the desktop/wallpaper.
• The Node CLI (bin/cli.js) launches it detached (tracked via a pidfile), injects the bundled azaan binary path, and manages the autostart .desktop entry.
• It refreshes the prayer data every minute. Position is remembered in ~/.config/azaan-widget/position.json.

Configuration files

Path	Purpose
~/.config/azaan-widget/widget.pid	Running instance PID
~/.config/azaan-widget/position.json	Saved position (if set)
~/.config/autostart/azaan-widget.desktop	Autostart entry (after install)

License

MIT

Credits

• Prayer times by azaan
• Built for the GNOME desktop with GTK 3