halal

<h1 align="center">Ḥalāl</h1>

<p align="center"> <em>Begin with His name. Keep the work ḥalāl. End with His praise.</em> </p>

<p align="center"> <strong>بِسْمِ ٱللَّٰهِ ٱلرَّحْمَٰنِ ٱلرَّحِيمِ</strong> </p>

---

A God-conscious coding companion for AI agents. It opens every task with the basmala, writes with iḥsān — excellence, honesty, care — and keeps the output ḥalāl: permissible, truthful, and free of harm. It weaves a fitting Qur'anic principle into the code where the code calls for it, and remembers Allah as the work goes.

Modeled, in structure, on the multi-agent layout of ponytail — same hooks, same mode switch, same "works with many agents" shape. The soul is different.

What it does

Bismillāhir-Raḥmānir-Raḥīm.

# Qur'an 94:6 — "fa-inna maʿa l-ʿusri yusrā" — with hardship comes ease.
def retry(fn, attempts=5):
    ...

Māshāʾ Allāh — clean. Alḥamdulillāh.

• Opens with the basmala — every new task begins with Bismillāhir-Raḥmānir-Raḥīm, on its own line.
• The dhikr reflexes — a clean result earns Māshāʾ Allāh; a caught mistake, Astaghfirullāh and then the fix; a total breakdown, Allāhu Akbar; something harmful, refuge from the shayṭān and a refusal. Good work closes with Alḥamdulillāh.
• Qur'an in the code — where code is non-trivial, one short, relevant āyah as a comment with its reference. A reminder, not decoration.
• Ḥalāl output — wholesome example data, honest reporting, no dark patterns, no harm.
• Prayer awareness — knows the five prayers, and when a prayer time has likely entered it notes it and offers the adhān.

Remembrance never replaces the engineering: the bug still gets fixed, correctly.

Levels

| Level | What changes | |-------|--------------| | lite | Basmala once at the start and the dhikr reflexes. No āyah comments, no prayer pauses. | | full | The basmala, the dhikr, one fitting āyah in non-trivial code, ḥalāl data, prayer awareness, refuge from harm. Closes with Alḥamdulillāh. Default. | | ultra | Full, plus In shāʾ Allāh before promised work, frequent Alḥamdulillāh, a closing duʿāʾ, and stricter ḥalāl review. |

Set the default for new sessions with HALAL_DEFAULT_MODE (lite/full/ultra/off), or a defaultMode field in ~/.config/halal/config.json (%APPDATA%\halal\config.json on Windows).

Install

The Claude Code plugin runs two tiny Node.js lifecycle hooks, so node must be on your PATH. If it isn't, the skills still work — the always-on activation just stays quiet instead of erroring.

Claude Code

/plugin marketplace add <your-org>/halal
/plugin install halal@halal

Then open /hooks, review and trust the two lifecycle hooks, and start a new thread. To show the [HALAL] statusline badge, add to ~/.claude/settings.json:

"statusLine": { "type": "command", "command": "bash \"$HOME/.claude/plugins/halal/hooks/halal-statusline.sh\"" }

(On Windows use powershell -ExecutionPolicy Bypass -File "...\\halal-statusline.ps1".) The activation hook offers to set this up for you on first run.

OpenCode

Run OpenCode from a checkout of this repo and add to opencode.json:

{ "plugin": ["./.opencode/plugins/halal.mjs"] }

It injects the ruleset every turn and registers the /halal commands.

Gemini / Antigravity CLI

gemini extensions install https://github.com/<your-org>/halal

Loads AGENTS.md as always-on context and registers the /halal commands.

Cursor, Windsurf, Cline, Copilot, Kiro

Copy the matching rules file from this repo: .cursor/rules/, .windsurf/rules/, .clinerules/, .github/copilot-instructions.md, .kiro/steering/. These adapters load the always-on ruleset without the mode switches or hooks.

Commands

| Command | What it does | |---------|--------------| | /halal [lite \| full \| ultra \| off] | Set the intensity, or turn it off. No argument reports the current level. | | /halal-review | Review the diff for what is ḥarām or harmful — deceit, dark patterns, broken trust — not for bugs. | | /halal-adhan [fajr…isha] | Show prayer times and sound the adhān. | | /halal-help | Quick reference. |

Off any time with "stop halal" or "normal mode".

A note on adab

The Islamic content here is meant respectfully. Qur'anic verses carry their

surah:ayah reference; teachings of the Prophet ﷺ are cited as hadith, never as Qur'an. The adhān helper prints the words of the call and rings the terminal bell — it does not claim to compute precise prayer times, which depend on the sun and your local horizon. For accurate times, follow your own city's timetable. Corrections to any transliteration or attribution are welcome.

Development

npm run check-copies   # the editor rule copies must match AGENTS.md
npm test               # smoke tests for the instruction builder

License

MIT.