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.
- 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, Quran.com Cloud Sync & Context Preview: Save bookmarks with timestamp and ayah position, sync your cloud bookmarks and reading sessions from Quran.com (via OAuth2 PKCE or browser sign-in bridge), and preview Uthmani Arabic script and English translation right on each bookmark card.
- Semantic "Find Ayah & Play" Search (
mcp.quran.ai): Search the Quran by natural-language meaning or topic (e.g.,"patience in hardship","mercy") or exact verse key (2:255) and jump straight to the matching Ayah's audio timestamp. - Live Now-Playing Ayah Reader & Inline Tafsir Drawer: View Uthmani Arabic script, M.A.S. Abdel Haleem translation, and an expandable Tafsir Ibn Kathir drawer directly inside the Now-Playing card.
- Quick Jump by Juz, Page, or Hizb: One-click navigation pills and CLI/IPC commands to jump directly to any Juz (1–30), Madinah Mushaf Page (1–604), or Hizb (1–60).
- 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) plus native Go Streamable HTTP client (cmd/quranctl/mcp.go) connected to Quran Foundation'shttps://mcp.quran.ai. - 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, Forgiving Search: Instant ranked search across 114 Surahs and 240+ reciters. Spelling, diacritics, hyphens and the "Al-" article don't matter:
yaseen,ya sin,يس,36,surah 36,36:5andpage 440all find Ya-Sin;juz 30lists every surah in the juz;the cow,kahforrahmanwork too. Reciters match on English or Arabic names with words in any order (alafasy mishary). Anything that finds no surah locally is sent to Quran.ai as a topic search.
The widget and the service both answer omarchy-shell IPC calls:
omarchy-shell quran-ui open # open the player popup
omarchy-shell quran-ui openTab reciter # surah | reciter | bookmarks | qurancom
omarchy-shell quran-ui search "juz 30" # open on the surah tab with a query filled in
omarchy-shell quran-ui search "patience" # topics go to Quran.ai semantic search
omarchy-shell quran status # playback state as JSON
omarchy-shell quran playSurah ar.alafasy 36 # play a surah by reciter id and numberInside the popup, j/k move through the visible list, Enter plays the
highlighted surah or selects the reciter, and Esc closes it.
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 --buildinstead of downloading prebuilt binaries.
omarchy plugin add https://github.com/szaidi-code/quran-plugin.git --enableOn first launch, the plugin automatically runs install.sh to install the audio
engine into ~/.local/bin and start the local streaming daemon. install.sh
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.
You can also run the installer manually at any time:
./install.shOptional: compile locally instead of downloading:
./install.sh --buildTo completely remove the szaidi.quran engine and its local data:
./uninstall.shIf 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.
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 testsThe 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.
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-pluginThe digests live in the source tree rather than inside the release archive, so they are not supplied by the artifact being verified.
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.
- 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.
quranctl search "patience in hardship"
quranctl ayah 2:255 --with-tafsir
quranctl navigate --juz 30
quranctl navigate --page 293
quranctl navigate --hizb 15
quranctl sync --login-browser
quranctl sync --pullThe service registers as the quran IPC target:
omarchy-shell quran status
omarchy-shell quran playSurah <reciter> <surah>
omarchy-shell quran search "<query-or-verse-key>"
omarchy-shell quran navigateJuz <1-30>
omarchy-shell quran navigatePage <1-604>
omarchy-shell quran syncBookmarks
omarchy-shell quran download <reciter> [surah]
omarchy-shell quran cacheInfo
omarchy-shell quran clearCacheSpecial thanks to AksharP5/omarchy-radio-atlas for showing how to approach Omarchy plugin integration and serving as a useful reference while building szaidi.quran.
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.
