🕌 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