dhikrncode

A small, calm companion that opens a dhikr or Qur'an window in your browser while your AI coding agent is working. When the agent finishes (or asks for input), the window winds down — quickly for dhikr, slowly for Qur'an reading — so the time you'd otherwise spend watching tokens scroll becomes time spent in remembrance.

Currently integrates first-class with Claude Code via its hooks system. Manual mode (dhikrncode start / stop) works with anything else.

┌────────────────────┐     ┌────────────────────┐     ┌──────────────────┐
│  Claude Code hook  │ ──▶ │   dhikrncode CLI   │ ──▶ │   local daemon   │
│  (settings.json)   │     │   (POST /event)    │     │  (state + WS)    │
└────────────────────┘     └────────────────────┘     └────────┬─────────┘
                                                               │
                                                               ▼
                                              ┌──────────────────────────┐
                                              │  browser tab — dhikr or  │
                                              │  Qur'an, with countdown  │
                                              └──────────────────────────┘

Install

Requires Node 18+.

npm install -g dhikrncode
dhikrncode

The first run drops you into a 3-question setup wizard:

Set up Claude Code hooks now? [Y]:
Mode — (1) dhikr   (2) qur'an [1]:
OS notifications when the agent is ready? [n]:

After that you can close the terminal — dhikrncode only runs when Claude Code triggers it, and shuts itself down after 30 minutes idle. The window pops up on its own.

dhikrncode off          # quick toggle (hooks stay; daemon drops events)
dhikrncode on           # quick toggle back
dhikrncode              # re-open the interactive shell
dhikrncode uninstall    # remove hooks, stop daemon, stop nagging

uninstall also remembers you opted out — running dhikrncode after that won't silently turn things back on. Type init inside the shell (or dhikrncode init) to opt back in.

Use

Just start Claude Code as you normally would:

claude

Send a prompt → a browser tab opens with dhikr (default) or Qur'an ayahs. When the agent finishes, a banner appears with a countdown.

Configure

Three equivalent ways — all writing the same ~/.config/dhikrncode/config.json:

Interactive shell (dhikrncode)

Run dhikrncode with no arguments in a terminal — same idea as typing claude — and you get a small REPL:

$ dhikrncode
dhikrncode v0.1.0 — type 'help' for commands, 'exit' to quit
mode: dhikr · daemon: down · notifications: off · integrations: claude-code, manual

› mode quran
mode: quran
› notifications on
notifications: on
› claude-code off
claude-code: off
› status
mode: quran · daemon: up · notifications: on (×1) · integrations: manual
› exit

If a daemon is running, every change pushes live to the open browser window. Type help inside the shell for the full command list.

Browser settings panel

Click the ⚙ gear in the top-right (or press ,). Change mode, surah, notifications, pacing, integrations — Save. Mode changes reload the page; everything else applies live.

One-shot CLI

dhikrncode config                          # interactive prompts
dhikrncode config --mode=quran --surah=1   # one-liner
dhikrncode config --notifications=true --repeat=3 --repeat-interval=20

Integrations

Per-source toggles let you keep the hooks installed but pause any one surface without uninstalling. Defaults: Claude Code CLI on, Manual on, Claude Desktop off.

| Setting | Default | Source | |--------------------------------------|---------|-----------------------------------------------------| | integrations.claudeCode.enabled | true | Claude Code in a real terminal (Terminal, iTerm, …) | | integrations.claudeDesktop.enabled | false | Claude Code running inside Claude Desktop | | integrations.manual.enabled | true | dhikrncode start/stop |

dhikrncode classifies each hook event by inspecting macOS's __CFBundleIdentifier env var (with TERM_PROGRAM as a fallback) and routes it to the matching toggle. The daemon log shows the classification on every event:

event: stop (phase=ready, source='claude-code-cli' — terminal bundle id: com.apple.Terminal)
event: stop skipped (source='claude-code-desktop' disabled — Anthropic desktop bundle id: com.anthropic.claudefordesktop)

Toggle in the shell:

› claude-code off       # silence the CLI integration
› claude-desktop on     # turn on the desktop one
› manual off

If the auto-detection misfires for your setup, override it on a per-process basis:

DHIKRNCODE_FORCE_SOURCE=claude-code-desktop claude

Notifications

OS notifications are off by default — the browser banner is the primary signal. Turn them on if you want an audible / system reminder when the agent is ready (you may want this if you Alt-Tab away frequently). You can also configure how many times to remind and at what interval, in case the first one doesn't catch your attention.

| Setting | Default | Notes | |------------------------------------|---------|------------------------------------| | notifications.enabled | false | Master switch | | notifications.events.done | true | Notify when agent finishes | | notifications.events.approval | true | Notify when agent needs input | | notifications.repeat | 1 | Total reminders per ready event | | notifications.repeatIntervalSeconds | 30 | Gap between reminders |

Repeats are cancelled automatically when you submit a new prompt.

Pacing — how the window closes

| Mode | Auto-close | Extension button | |---------|------------|----------------------| | Dhikr | 5 s | Stay → +15 s | | Qur'an | 30 s | Finish ayah → +30 s |

window.close() is best-effort — some browsers don't allow it for tabs the user could have opened themselves. When close is blocked, the banner shifts to "✓ You can close this tab now."

Keyboard shortcuts

Dhikr mode

| Key | Action | |---------------------|-------------------| | ← / h | Previous dhikr | | → / l | Next dhikr | | Space / ↓ / j | Tap counter (+1) | | R / 0 | Reset counter |

Qur'an mode

| Key | Action | |-----------|-------------------| | ← / h | Previous ayah | | → / l | Next ayah | | ↓ / j | Next surah | | ↑ / k | Previous surah | | S | Focus surah list |

Always

| Key | Action | |-----------------|------------------------------| | , | Open settings panel | | Esc | Close settings or banner | | E / + | Extend countdown (in banner) | | C | Close now (in banner) |

Manual mode (no hooks)

If you don't use Claude Code, or want to test the UI:

dhikrncode start    # open the window now
dhikrncode stop     # signal "ready" → countdown starts
dhikrncode kill     # stop the daemon
dhikrncode restart  # kill + start

Bundled Qur'an content

Ships with: Al-Fatiha (1), Al-Asr (103), Al-Kawthar (108), Al-Ikhlas (112), Al-Falaq (113), An-Nas (114).

Each surah is a JSON file in data/quran/ with attribution. To add more, see CONTRIBUTING.md.

Privacy

• Everything is local. The daemon binds to 127.0.0.1 only.
• No telemetry, no analytics, no remote calls.
• The daemon idles down after 30 minutes of no activity.

Commands reference

| Command | What it does | |-------------------------|-------------------------------------------------| | dhikrncode | Interactive shell (TTY only) | | dhikrncode init | Install Claude Code hooks | | dhikrncode uninstall | Remove them | | dhikrncode config | Configure (interactive or via flags) | | dhikrncode start | Open the window now (manual) | | dhikrncode stop | Signal "ready" now | | dhikrncode kill | Stop the daemon | | dhikrncode restart | Kill + start | | dhikrncode daemon | Run daemon in foreground (debug) | | dhikrncode hook <e> | Internal: invoked by Claude Code | | dhikrncode help | Help |

Contributing

Issues and PRs welcome. Please read CONTRIBUTING.md for the project philosophy (small, calm, local-first), how to verify Qur'an content, and the dev workflow.

License

MIT — see LICENSE. Bundled Qur'an translations are credited inline in each JSON file.