Quran Plugin for Omarchy

An elegant, feature-rich Quran recitation player and reader companion for the Omarchy Linux desktop environment. Listen to recitations from world-renowned Qaris, track your reading position across Surahs, Ayahs, Juzs, and Pages, bookmark your progress with instant one-click Pick Up, and explore rich Quranic resources with Quran.com integration.

---

Highlights & New Features

• Spacious & Modern UI: Roomy 440px layout designed to integrate seamlessly with Omarchy's system theme and typography.
• Monochrome Closed Mushaf Icon: Uniform, clean icon matching the system bar theme.
• Reader Location Tracker ("Where The Reader Is"): Live indicator computing current Surah, estimated Ayah, Juz, Hizb, Page number in the Madinah Mushaf, and progress percentage.
• Reading Bookmarks & Instant "Pick Up": Save bookmarks with timestamp and ayah position, and pick up right where you left off anytime with a single click.
• Quran.com Explore Suite: Direct one-click access to the current Ayah on Quran.com, Ibn Kathir/Sa'di Tafsir, word-by-word morphology/grammar, Madinah Mushaf layout, and the personalized reading experience guide.
• Model Context Protocol (MCP) Server: Built-in Python MCP server (mcp/server.py) exposing reader position, verse lookups, player controls, and bookmark management to AI coding assistants (Claude, Antigravity, etc.).
• Instant Streaming & Offline Audio: Fast byte-range streaming via a hardened loopback Go audio proxy (quranproxyd) with deep media validation and background full-mushaf caching.
• Multilingual Search: Live instant search across 114 Surahs and reciters in Arabic, English, and 9 additional languages.

Dependencies

• mpv (runtime; the player).
• mpv-mpris (recommended for system media control).
• file (runtime, used by the media validator; falls back gracefully if missing).
• ffprobe (optional; deep validation when present).
• Go 1.22+ — only if you use install.sh --build instead of downloading prebuilt binaries.

Install

omarchy plugin add https://github.com/szaidi-code/quran-plugin.git --enable

Then install the audio engine. This downloads the archive for a pinned, immutable release tag and verifies it against SHA-256 digests committed in this repository (checksums/<tag>.sha256) before extracting it. Installation fails closed if those digests are missing or do not match:

./install.sh

Optional: compile locally instead of downloading:

./install.sh --build

Then restart your Omarchy shell.

Uninstall

To completely remove the szaidi.quran engine and its local data:

./uninstall.sh

If you installed the engine with a custom prefix, pass the same prefix when uninstalling:

./uninstall.sh --prefix "$HOME/.local/share/bin"

The uninstall script removes the installed quranproxyd and quranctl binaries along with szaidi.quran's downloaded audio, cache, and settings.

The plugin installs entirely within your own user account; elevated privileges are never requested or used.

After uninstalling, restart your Omarchy shell or disable/remove the plugin to unload the running engine.

Build from source

make build          # dev build into ./bin (unstripped)
make install        # installs ./bin binaries into ~/.local/bin
make prebuilt       # static, stripped binaries for amd64 + arm64
make dist           # tar.gz + SHA-256 archives per arch (for releases)
make test           # Go unit tests

The Go module has zero external dependencies (go.mod has no require block), so builds work offline.

Release archives are built and attested via GitHub Actions on version tags. See .github/workflows/release.yml.

Verifying a download

install.sh performs both checks below automatically, refusing to install on any mismatch. To verify by hand:

# 1. Digest committed in this tree (the fail-closed gate)
sha256sum -c <(grep linux-amd64.tar.gz checksums/v1.1.2.sha256)

# 2. GitHub build provenance, bound to this repository
gh attestation verify linux-amd64.tar.gz --repo szaidi-code/quran-plugin

The digests live in the source tree rather than inside the release archive, so they are not supplied by the artifact being verified.

Security

This plugin was written with the security model of the Omarchy shell in mind (plugins run as unsandboxed code, so they are only as safe as their code):

• The proxy binds 127.0.0.1 only, and every request requires a per-run 32-hex token shared via a 0600 handoff file in a 0700 runtime dir.
• Origin URLs are built only from the validated reciter catalog and validated through a strict allowlist — no arbitrary URLs, no redirects followed, DNS is pinned to the allowlisted host.
• The daemon never writes quran.json; it reads the catalog and signals progress over stdout events. There is exactly one writer for your state file.
• Media is validated (size cap, MIME, ffprobe) before a file is accepted as a permanent download; downloads stage through unique temp files and atomic renames.
• No elevated privileges, no install hooks, no writes outside your own state/cache/runtime dirs.
• Release archives are pinned to an immutable tag, downloaded within strict producer-side size and timeout bounds, and verified against digests committed in this tree before extraction; the installer fails closed when integrity metadata is missing, mismatched, or oversized.

Usage

• Left-click the bar icon to open the popup and select a surah to play.
• Right/middle-click toggles play/pause; scroll wheel moves prev/next surah.

IPC

The service registers as the quran IPC target:

omarchy-shell quran status
omarchy-shell quran playSurah <reciter> <surah>
omarchy-shell quran download <reciter> [surah]
omarchy-shell quran cacheInfo
omarchy-shell quran clearCache

Special Thanks

Special thanks to AksharP5/omarchy-radio-atlas for showing how to approach Omarchy plugin integration and serving as a useful reference while building szaidi.quran.

License

MIT — see LICENSE.

---

This repo used to be a self-contained shell plugin; it is now a single repository hosting both the plugin and its Go audio engine. See docs/PLAN.md for the design history.