/website-blocker-macos

Primary LanguageJavaScript

Website Blocker for macOS (Node.js)

  • Browser-agnostic, system-wide blocking by editing /etc/hosts.
  • Supports one-off sessions by date/time and recurring daily/weekly schedules.
  • Installs a root launchd daemon that enforces the schedule every minute.

Requirements

  • macOS
  • Node.js 16+ (uses Intl time zone support)

Quick Start

  • Install globally: npm install -g website-blocker-macos (or from this repo: npm i -g .)
  • Create config: website-blocker init-config
  • Add domains and schedules with helper commands (below).
  • Install daemon (requires admin):
    • sudo website-blocker install-daemon --config "$HOME/.config/website-blocker/config.json"

Uninstall the daemon:

  • sudo website-blocker uninstall-daemon

Run once (manual tick) to apply/remove based on current time:

  • sudo website-blocker tick --config "$HOME/.config/website-blocker/config.json"

Show status (no sudo needed):

  • website-blocker status --config "$HOME/.config/website-blocker/config.json"

Config File

  • Default path: ~/.config/website-blocker/config.json
  • Specify another path with --config PATH.

Example (examples/config.example.json): { "domains": ["twitter.com", "news.ycombinator.com"], "sessions": [ {"start": "2025-09-10T09:00:00-04:00", "end": "2025-09-10T17:00:00-04:00"} ], "recurring": [ {"type": "daily", "start_time": "09:00", "end_time": "17:00", "tz": "America/New_York"}, {"type": "weekly", "days": ["Mon","Tue","Wed","Thu","Fri"], "start_time": "09:00", "end_time": "17:00", "tz": "America/New_York"} ] }

Notes:

  • daily/weekly support overnight ranges (e.g., 22:00→07:00).
  • If tz is omitted, local system time is used.
  • One-off sessions should use ISO8601 with timezone.

Helper Commands

  • Add/remove domains:
    • website-blocker add-domain twitter.com
    • website-blocker remove-domain twitter.com
  • Add recurring rules:
    • website-blocker add-daily 09:00 17:00 --tz America/New_York
    • website-blocker add-weekly Mon,Tue,Wed,Thu,Fri 09:00 17:00 --tz America/New_York

How it works

  • A launchd daemon runs as root every minute and updates a managed block in /etc/hosts:
    • Between # website-blocker-macos START and # website-blocker-macos END.
    • Domains are redirected to 127.0.0.1 and ::1.
  • When no rule is active, the managed block is removed.

Troubleshooting

  • After changing the config, the next minute tick applies it, or run tick manually.
  • Flush DNS cache if needed: sudo dscacheutil -flushcache; sudo killall -HUP mDNSResponder
  • If the daemon doesn’t appear to run, check logs:
    • /var/log/website-blocker-macos.out.log
    • /var/log/website-blocker-macos.err.log

For detailed instructions, see docs/USAGE.md.