halal
God-conscious coding mode. Opens with Bismillah, keeps the work halal — honest, permissible, harmless — weaves Qur'anic principles into the
Open source Open in the app JSON README (API)
About
God-conscious coding mode. Opens with Bismillah, keeps the work halal — honest, permissible, harmless — weaves Qur'anic principles into the code, and remembers Allah as it goes.
Details
- Kind
- Plugins
- Topic
- No topic detected
- Publisher
- yunst047
- Origin
- gemini
- Category
- ferramentas
- Version
- 1.0.0
- Forks
- 1
- Last push
- 2026-06-22T09:52:50Z
- Repository state
- ativo
- Language
- JavaScript
- License
- MIT
- Added
- 2026-08-30 14:13:39
- Updated
- 2026-08-30 14:13:39
- Origin id
yunst047/halal-skill
README
<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](https://github.com/DietrichGebert/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`:
```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`:
```json
{ "plugin": ["./.opencode/plugins/halal.mjs"] }
```
It injects the ruleset every turn and registers the `/halal` commands.
### Gemini / Antigravity CLI
```bash
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/`](.cursor/rules/), [`.windsurf/rules/`](.windsurf/rules/),
[`.clinerules/`](.clinerules/), [`.github/copilot-instructions.md`](.github/copilot-instructions.md),
[`.kiro/steering/`](.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
```bash
npm run check-copies # the editor rule copies must match AGENTS.md
npm test # smoke tests for the instruction builder
```
## License
[MIT](LICENSE).