shabbat-anchors

name	shabbat-anchors
description	Get candle-lighting, havdalah, sunset and tzeit times plus a day classification (shabbat / yom tov / erev chag / chol hamoed / fast day) for a date range in an Israeli city. Use as the calendar basis for resolving opening hours stated relative to Shabbat, or whenever you need to know what kind of day a given Israeli date is.

Shabbat and chag anchors

Fetches the boundary times that Shabbat-relative opening hours are measured from, and classifies each date. Backed by the Hebcal REST API — no API key, no MCP server, no plugin dependencies.

Command

python3 ${CLAUDE_PLUGIN_ROOT}/scripts/israel_hours.py anchors \
  --city jerusalem --from 2026-09-10 --days 7

Location can be given three ways:

Flag	Use when
--city <name>	One of the recognised cities. English or Hebrew (ירושלים).
--geonameid <id>	Anywhere else — the preferred fallback.
--latlon LAT,LON	Last resort only. Loses the local candle-lighting custom.

Do not reach for --latlon. Hebcal applies a location's candle-lighting custom only when addressed by city name or geonameid. Jerusalem by geonameid lights 40 minutes before sunset (18:56 on 2026-07-31); the same coordinates by lat/lon give 19:16. A silent 20-minute error. Look the place up on geonames.org and pass --geonameid instead.

israel_hours.py cities lists the 56 bundled places; cities --search <term> filters them. Lookup is forgiving — English, Hebrew, and romanisation variants all resolve (kiryat ata, Qiryat Ata, צפת, Tsfat, safed, TLV, Tel Aviv, Israel).

Anything smaller than roughly 35,000 people is not bundled; use --geonameid.

Output

One record per date:

{
  "date": "2026-09-13",
  "weekday": "sun",
  "day_type": "yom_tov",
  "rest_day": true,
  "labels": ["Rosh Hashana II"],
  "anchors": {
    "sunrise": "...", "sunset": "...", "tzeit": "...", "chatzot": "...",
    "candle_lighting": "...", "havdalah": "2026-09-13T19:24:00+03:00"
  },
  "notes": []
}

Day types

weekday, erev_shabbat, shabbat, erev_yom_tov, yom_tov, shabbat_yom_tov, yom_kippur, tisha_bav, chol_hamoed, fast_day.

rest_day is true for shabbat, yom_tov, shabbat_yom_tov and yom_kippur.

Anchors

sunrise, sunset, chatzot and tzeit exist every day. candle_lighting and havdalah exist only on the days they occur — a Tuesday has neither. Code that consumes this must handle their absence.

tzeit defaults to Hebcal's tzeit7083deg (three medium stars). Pass --tzeit tzeit85deg for the stringent reckoning, which runs ~7 minutes later. Havdalah as returned in anchors is Hebcal's own nightfall calculation and is the right anchor for "after Shabbat goes out" phrasing.

Things worth knowing

• Israel schedule is always used (i=on): one-day yom tov, not two. Rosh Hashana is still two days, correctly.
• Candle-lighting offset is per-city and Hebcal handles it. Jerusalem uses 40 minutes before sunset; Haifa and Zikhron Ya'aqov 30; everywhere else 20. Never hardcode an offset, and never address a location by bare lat/lon — a Jerusalem-vs-Tel-Aviv mix-up is a ~20 minute error in every derived time.
• Yom tov falling on Shabbat is classified shabbat_yom_tov and has one continuous rest period with havdalah only at the end.
• The range is padded by a day on each side internally, so erev-chag detection and past-midnight windows work at the edges of the requested range.