SelfControl Scheduler

Automatically block distracting websites on a schedule using SelfControl for macOS.

Why?

SelfControl is great for blocking distracting websites, but you have to manually start it each time. This tool automates that by letting you define a schedule (e.g., block social media during work hours) and it handles the rest.

Features

• Schedule website blocking for specific hours
• Supports overnight blocks (e.g., 10pm to 7am)
• Weekday-only option
• Uses your existing SelfControl blocklist
• Simple commands: on, off, test, status
• Easy to configure via YAML file

Requirements

• macOS 10.15+
• SelfControl 4.0+
• Python 3 (comes with macOS)

Installation

Quick Install

curl -fsSL https://github.com/bugrakocak/selfcontrol-scheduler/main/install.sh | bash

Manual Install

git clone https://github.com/bugrakocak/selfcontrol-scheduler.git
cd selfcontrol-scheduler
./install.sh

Via Homebrew (coming soon)

brew install selfcontrol-scheduler

Usage

# Check current status
selfcontrol-scheduler status

# Test with a 1-minute block
selfcontrol-scheduler test

# Turn on automatic blocking
selfcontrol-scheduler on

# Turn off automatic blocking
selfcontrol-scheduler off

# Edit your schedule
selfcontrol-scheduler config

# Remove everything
selfcontrol-scheduler uninstall

Configuration

Edit ~/.config/selfcontrol-scheduler/config.yaml:

enabled: true

# Use blocklist from SelfControl.app
use_existing_blocklist: true

# Or define your own blocklist:
# use_existing_blocklist: false
# blocklist:
#   - twitter.com
#   - reddit.com
#   - youtube.com

# Block schedules (24-hour format)
schedules:
  # Morning focus
  - start: "09:00"
    end: "12:00"

  # Afternoon focus
  - start: "13:00"
    end: "17:00"

  # Overnight (spans midnight)
  - start: "22:00"
    end: "07:00"

# Only block on weekdays
weekdays_only: true

How It Works

1. A launchd job runs at the start of each scheduled block period
2. The script checks if you're within a blocking period
3. If yes, it starts a SelfControl block that ends at the period's end time
4. SelfControl handles the actual blocking (can't be bypassed, even with a restart)

Important Notes

• Blocks can't be canceled early - This is by design (SelfControl's core feature)
• Test first - Use selfcontrol-scheduler test before turning it on
• Timezone aware - Works correctly across timezones

Troubleshooting

"SelfControl is not installed"

Install SelfControl first:

brew install --cask selfcontrol

"No blocklist found"

Add sites to block in SelfControl.app first, or define them in the config file.

Block doesn't end on time

SelfControl blocks are enforced at the system level. In rare cases, you may need to restart your Mac for the block to fully release.

Uninstall

selfcontrol-scheduler uninstall

Or manually:

launchctl unload ~/Library/LaunchAgents/com.selfcontrol.scheduler.plist
rm ~/Library/LaunchAgents/com.selfcontrol.scheduler.plist
rm ~/.local/bin/selfcontrol-scheduler
rm -rf ~/.config/selfcontrol-scheduler
rm -rf ~/.local/share/selfcontrol-scheduler

License

MIT License - see LICENSE

Contributing

Contributions welcome! Please open an issue or PR.

Credits

• SelfControl - The amazing app that makes this possible