Israeli Home Front Command alerts — delivered to your loved ones' Telegram chat.

עברית · Русский

Caution

EasyOref does not replace official Home Front Command alerts. It supplements them — keeping your loved ones abroad informed. Always follow Home Front Command instructions!

Why

During a rocket attack, your loved ones abroad see "MISSILES HIT TEL AVIV" on news.

They don't know:

• Is it your neighborhood or 200 km away?
• Are you safe?
• Should they worry?

Nothing solves this for them today. Alert apps with area filtering — for you in Israel. Cell Broadcast alerts — for you in Israel.

Features

• 4 languages — Russian, English, Hebrew, Arabic
• 3 alert types — early warning, siren, all-clear
• Custom messages — your own text and media per alert type

Install

1. Install Node.js

Windows

Download the installer from nodejs.org (LTS, 22+). Run it, click "Next".

macOS

brew install node

Or download from nodejs.org.

Linux / Raspberry Pi

curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt install -y nodejs

2. Set up Telegram

1. Message @BotFather → /newbot → copy the token
2. Add the bot to your Telegram chat or channel
3. Forward any message from that chat to @userinfobot → copy the chat ID

3. Find your city ID

Open cities.json, find your city, copy the id number.

Example: "id": 722 = Tel Aviv — South & Jaffa.

4. Run setup

npx easyoref init

The wizard asks for language, token, chat ID, and city ID. Config is saved to ~/.easyoref/config.yaml.

5. Start the bot

npx easyoref

Done. The bot will message your chat whenever the Home Front Command issues an alert for your area.

The bot needs to run 24/7 — on a Raspberry Pi, server, or always-on computer. Guides: RPi · Local

How it works

EasyOref runs two layers:

Core layer — always on, <1s latency

• Polls Pikud HaOref API every 2 seconds
• Filters alerts by city ID (Iron Dome zone-aware)
• Delivers to Telegram instantly

Agentic enrichment layer — LangGraph pipeline per alert

collectAndFilter → extract → vote → [clarify → revote] → editMessage

1. collectAndFilter — fetches channel posts, deterministic noise filter, channel tracking
2. extract — two-stage LLM: cheap channel relevance pre-filter → expensive structured extraction (rocket count, intercepts, impact zone, country origin)
3. vote — consensus across multiple extractions, confidence scoring
4. clarify (conditional) — triggered on low confidence or suspicious single-source claims; LLM invokes tools to resolve:
   • read_telegram_sources — live MTProto fetch from IDF/news channels
   • alert_history — verifies claims against Pikud HaOref history API
   • resolve_area — Iron Dome zone proximity check
   • betterstack_log — queries enrichment pipeline logs
5. revote — re-runs consensus with clarified data
6. editMessage — in-place Telegram edit with citations

LangGraph MemorySaver checkpoints state per alertId. Graceful degradation: ai.enabled: false → deterministic delivery only, zero LLM dependency.

Configuration

Config file: ~/.easyoref/config.yaml. Created by npx easyoref init.

Full reference: config.yaml.example.

Key	Default	Description
city_ids	—	required. Find city IDs
telegram.bot_token	—	required. Token from @BotFather
telegram.chat_id	—	required. Chat ID (negative number)
language	ru	ru en he ar
alert_types	all	early siren resolved
gif_mode	none	funny_cats none
title_override.*	—	Custom title per alert type
description_override.*	—	Custom description per alert type

License

MIT — Mikhail Kogan, 2026