📖 quran.sh

A fast, offline-first Quran CLI and TUI reader built with Bun and TypeScript

Features

📚 Reading

• Offline-First — All data bundled, works without internet
• Multi-Pane Reader — Arabic (top), Translation + Transliteration (split below)
• 10 Languages — Bengali, English, Spanish, French, Indonesian, Russian, Swedish, Turkish, Urdu, Chinese — press l to cycle
• Arabic Text Shaping — Proper connected Arabic rendering via arabic-reshaper
• Verse Flow Modes — Stacked, inline, or continuous flow — press F to cycle
• Arabic Layout — Configurable alignment (A) and width (W)

🎨 Design

• 12 Dynasty Themes — Mamluk, Ottoman, Safavid, Andalusian, Maghribi, Madinah, Umayyad, Abbasid, Fatimid, Seljuk, Mughal — each with unique ornaments, borders and color palettes inspired by Islamic manuscript illumination
• Light & Dark Mode — Auto-detection + manual toggle
• Themed Progress Bars — Custom ASCII progress indicators in title bars using dynasty-specific ornament characters
• Focus Indicators — Heavy borders + diamond icon on the focused pane

🔖 Study Tools

• Bookmarks — Mark and revisit favorite verses
• Cues — 9 quick-navigation slots (1–9) for instant jumping
• Reflections — Personal notes attached to any verse
• Activity Panel — Toggleable right panel listing all bookmarks, cues, and reflections
• Full-Text Search — Search across all translations with /
• Command Palette — Quick access to all commands with Ctrl+P

📊 Progress Tracking

• Reading Mode — Toggle between browsing (no tracking) and reading (tracks every verse) with m
• Surah Completion — When navigating away from a surah in reading mode, prompted to mark it as complete
• Reading Stats — Sidebar widget showing verses read, unique verses, surahs touched, and surahs completed — filterable by Today, Week, Month, All Time, and Session
• Streak Tracking — Current streak, longest streak, and total reading days via CLI
• Verse Logging — Log individual verses or full surahs as read via CLI

💾 Persistence

• SQLite Database — All bookmarks, cues, reflections, reading logs, and preferences stored locally
• Auto-Restore — Selected surah, verse position, theme, language, layout, sidebar/panel visibility, and reading mode all persist across sessions

Installation

# Run directly (no install)
bunx quran.sh

# Global install
bun install -g quran.sh

# Or with npm
npm install -g quran.sh

Usage

CLI Commands

# Launch interactive TUI
quran

# Read a surah (by number or name)
quran read 1
quran read al-fatihah

# Read a specific verse
quran read 2:255

# Search for verses
quran search "merciful"

# Log reading progress
quran log 1
quran log 2:255

# View reading streak
quran streak

TUI Keyboard Shortcuts

Navigation

Key	Action
Tab	Cycle focus: Sidebar → Arabic → Translation → Transliteration → Panel
Shift+Tab	Cycle sidebar focus: Surah List ↔ Reading Stats
↑/↓ or j/k	Navigate surahs or verses
Enter	Select surah (in sidebar)
1-9	Jump to cue slot

Pane Toggles

Key	Action
a	Toggle Arabic pane
t	Toggle Translation pane
r	Toggle Transliteration pane
s	Toggle sidebar
B	Toggle activity panel (Bookmarks / Cues / Reflections)

Study

Key	Action
b	Toggle bookmark on current verse
R	Add/edit reflection
! to (	Set cue 1–9 (Shift+1–9)
/	Search verses
m	Toggle Reading/Browsing mode

Display

Key	Action
T	Cycle dynasty theme
D	Cycle light/dark mode
+/-	Increase/decrease verse spacing
A	Cycle Arabic alignment
W	Cycle Arabic width
F	Cycle verse flow mode

General

Key	Action
Ctrl+P	Open command palette
?	Show/hide help dialog
ESC	Dismiss dialog / Clear search
q	Quit

Data Source

• Translations from quran-json
• 114 surahs, 6,236 verses
• 10 languages: Bengali, English, Spanish, French, Indonesian, Russian, Swedish, Turkish, Urdu, Chinese

Development

# Clone
git clone https://github.com/smashah/quran.sh.git
cd quran.sh

# Install dependencies
bun install

# Run TUI
bun run src/index.ts

# Run CLI
bun run src/index.ts read 1

# Run tests
bun test

# Build standalone binary
bun run build
# → outputs ./dist/quran

Recording Demos

Demo recording scripts are in demos/. To record a TUI demo:

# 1. Start a tmux session
tmux new-session -d -s demo -x 120 -y 35

# 2. Start terminalizer inside it
tmux send-keys -t demo 'terminalizer record --config demos/tui-demo.yml demos/tui-full -k' Enter

# 3. Run the keystroke automation (in another terminal)
bash demos/send-keys.sh

# 4. Render to GIF
terminalizer render demos/tui-full

License

MIT © smashah

Credits

• Built with Bun
• UI powered by OpenTUI
• Arabic shaping via arabic-reshaper
• Data from quran-json

---

Made with ❤️ for the Muslim community