pi-quran-verses

Pi extension that shows a Quran verse next to the working spinner while the agent is responding.

Only complete-sentence verses are used. Incomplete phrases, mid-sentence connectors, letter names (muqattaʿāt), and unfinished translation fragments are filtered out.

Install

From npm

pi install npm:pi-quran-verses

From git

pi install git:github.com/mwijanarko1/pi-quran-verses

Local path

pi install /absolute/path/to/pi-quran-verses
# or
pi install ./pi-quran-verses

Temporary test without installing:

pi -e ./pi-quran-verses
# or
pi -e npm:pi-quran-verses

Then /reload or restart Pi.

Publish (maintainers)

npm login
npm publish
# or
bun publish

Verify:

npm view pi-quran-verses version
pi install npm:pi-quran-verses

Usage

While Pi is working, the spinner message is replaced with a random verse from the selected translation:

A new verse is chosen on each agent turn (turn_start).

Command

| Command | Description | |---|---| | /quran-lang | Choose language, then (if needed) translation |

Settings are stored at:

~/.pi/agent/pi-quran-verses.json

Example:

{
  "editionId": "en.saheeh"
}

Languages and translations

Modeled on QuranScroll’s translation manifest.

| Language | Edition ID | Translator | |---|---|---| | Arabic | ar.uthmani | Uthmani | | English | en.saheeh | Saheeh International (default) | | English | en.haleem | MAS Abdel Haleem | | English | en.bridges | Bridges Translation | | Spanish | es.isa-garcia | Sheikh Isa Garcia | | German | de.bubenheim | Bubenheim & Elyas | | French | fr.rashid-maash | Rashid Maash | | Urdu | ur.tafheem-maududi | Tafheem e Qur'an - Maududi | | Urdu | ur.maududi-roman | Abul Ala Maududi (Roman Urdu) | | Urdu | ur.tafsir-usmani | Tafsir E Usmani | | Urdu | ur.bayan-ul-quran | Bayan-ul-Quran | | Indonesian | id.indonesian | Indonesian Islamic Affairs Ministry |

How verse selection works

1. Start from the complete-thought list in source/quotable-verses.md (from the Quran wiki synthesis).
2. Gate those refs through an English Saheeh International sentence filter so only standalone sentences remain.
3. Keep spinner-friendly length (≤ 140 characters).
4. Build per-language verse pools into extensions/data/editions.json.

At runtime the extension only reads extensions/data/editions.json and the user settings file. No network calls.

Sentence filter (high level)

Rejected examples:

• letter names: Alif, Lām, Meem.
• unfinished endings: trailing -, ,, ;
• short fragments
• dependent openers needing prior context (Who…, That they…, Abiding…)
• unclosed quotes/brackets

Package layout

pi-quran-verses/
├── package.json                 # pi package manifest
├── README.md
├── LICENSE
├── extensions/
│   ├── index.ts                 # extension entrypoint
│   └── data/
│       └── editions.json        # bundled verse pools
├── scripts/
│   └── build-verses.mjs         # rebuild editions.json
└── source/                      # build inputs (not published)
    ├── quotable-verses.md
    ├── sentence-refs.json
    └── translations/

Published package contents (files in package.json):

• extensions/
• README.md
• LICENSE

Rebuild verse data

If you update the quotable list or translation sources:

node scripts/build-verses.mjs

Then /reload Pi.

Translation source files live in source/translations/ (QuranScroll QUL simple JSON format, plus Arabic and German).

Development checks

npm pack --dry-run
pi -e . --list-models

Notes

• This package does not send verses to the model context; it only changes the working spinner UI.
• Default edition is en.saheeh.
• German is included even though QuranScroll currently does not ship it; other languages follow QuranScroll’s editions.

More docs

• docs/EXTENSION.md — runtime behavior, data model, build pipeline, verification