islamic-companion

name	islamic-companion
description	Unified Islamic utilities for prayer times, fasting schedules, and Zakat calculations using a shared configuration.

Islamic Companion Skill

Unified tool for prayer times, fasting schedules, and Zakat calculations.

This skill consolidates Islamic utilities into a single CLI with shared configuration and efficient caching.

Features

• Prayer Times: Retrieve daily prayer times (Fajr, Dhuhr, Asr, Maghrib, Isha).
• Fasting: Check Imsak and Maghrib times for fasting.
• Zakat: Calculate Nisab thresholds for Gold and Silver based on current market prices.
• Quran: Search for verses by keyword or fetch specific Surah/Ayah with translation.
• Calendar: Generate a monthly prayer schedule for any city.
• Quotes: Fetch and display random Islamic quotes or setup daily automation.
• Scheduler: Generate OpenClaw cron commands to schedule daily prayer reminders.
• Caching: Minimizes API calls by caching daily results locally.

Usage

Run the CLI using the bash script:

# Get today's prayer times
./bin/islamic-companion prayer --today

# Setup daily quote automation
./bin/islamic-companion quotes --setup

# Get a random quote
./bin/islamic-companion quotes --random

# Get monthly calendar (Example: Serang, Banten)
./bin/islamic-companion calendar --city "Serang" --month 2 --year 2026

# Sync prayer schedule to cron (generates commands)
./bin/islamic-companion prayer --sync

# Check fasting times (Imsak/Maghrib)
./bin/islamic-companion fasting --today

# Check Zakat Nisab values
./bin/islamic-companion zakat --nisab

# Search Quran for keyword
./bin/islamic-companion quran --search "sabar"

# Get specific Surah (e.g., Al-Fatihah)
./bin/islamic-companion quran --surah 1

# Get specific Ayah (e.g., Al-Baqarah:255)
./bin/islamic-companion quran --surah 2 --ayah 255

Configuration

Edit skills/islamic-companion/config.json to set your location and calculation method. Note: config.bash is auto-generated from config.json for performance.

{
  "location": {
    "latitude": -6.2088,
    "longitude": 106.8456,
    "name": "Jakarta"
  },
  "calculation": {
    "method": 20,
    "school": 0
  },
  "zakat": {
    "currency": "IDR",
    "gold_gram_threshold": 85,
    "api_key": ""
  },
  "quran_language": "id"
}

Calculation Methods

• Method 20: Kemenag RI (Indonesia)
• School 0: Standard (Shafi, Maliki, Hanbali)
• School 1: Hanafi

Intent Mappings (for Agent)

User Intent	Command Executed
"Get prayer times"	./bin/islamic-companion prayer --today
"Show me the calendar for [City]"	./bin/islamic-companion calendar --city [City]
"Setup daily Islamic quotes"	./bin/islamic-companion quotes --setup
"Give me a random Islamic quote"	./bin/islamic-companion quotes --random
"Sync prayer schedule"	./bin/islamic-companion prayer --sync
"When is Imsak?"	./bin/islamic-companion fasting --today
"Check Zakat Nisab"	./bin/islamic-companion zakat --nisab
"Search Quran for [keyword]"	./bin/islamic-companion quran --search "[keyword]"
"Read Surah [Name/Number]"	./bin/islamic-companion quran --surah [Number]
"Read Surah [Number] Ayah [Number]"	./bin/islamic-companion quran --surah [Number] --ayah [Number]

Dependencies

• System: bash, curl, jq (highly recommended)
• Python (Optional for some features): python3, requests (Install via pip install -r requirements.txt)

Security & Privacy

[!WARNING] API Keys: The Zakat feature uses an API key. You can store it in config.json (less secure) or export it as an environment variable ZAKAT_API_KEY (recommended).

[!IMPORTANT] Automation: The --sync and --setup commands generate cron schedules. Always review the output before adding it to your system crontab.

Installation

1. Clone the repository or download the skill.
2. Install Python dependencies:

   pip install -r requirements.txt
   

3. Ensure curl is installed. jq is recommended for JSON parsing speed and reliability.

Usage

Run the CLI using the bash script wrapper, which handles configuration loading and environment setup:

# Get today's prayer times (uses HTTPS)
./bin/islamic-companion prayer --today