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.