Focus Blocker 🚫

A simple terminal-based website blocker for macOS that helps you stay focused by blocking distracting websites.

Features

• ✅ Simple Commands: Just run focus to block sites and unfocus to unblock them
• ✅ Do Not Disturb Integration: Automatically enables/disables macOS Do Not Disturb mode
• ✅ Smart Session Management: Automatically saves and restores browser tabs when activating focus mode
• ✅ Intelligent URL Filtering: Skips restoring tabs from blocked sites - no wasted effort
• ✅ Multi-Browser Support: Works with Chrome, Safari, Brave, and Comet browsers (session management for Chrome, Safari, Brave)
• ✅ Spotify Integration: Launch focus mode with custom playlists for enhanced productivity
• ✅ Playlist Management: Add, remove, and list custom Spotify playlists
• ✅ Customizable Block List: Easily add/remove sites from your block list
• ✅ Works System-Wide: Blocks websites in all browsers and applications
• ✅ No Background Processes: Uses the system's hosts file, no daemon required
• ✅ Terminal Interface: Perfect for developers who live in the terminal
• ✅ Clean Output: Concise, informative messages without clutter
• ✅ Visual Status: See which sites are blocked and your current focus status

How It Works

Focus Blocker works by modifying your system's /etc/hosts file to redirect blocked websites to 127.0.0.1 (localhost). This means when you try to visit a blocked site, it won't be able to connect, effectively blocking access.

Browser Session Management

When you activate focus mode, Focus Blocker intelligently manages your browser tabs:

1. Saves all open tabs from Chrome, Safari, and Brave using AppleScript
2. Force closes browsers using SIGKILL to prevent automatic tab restoration
3. Updates the hosts file to block distracting websites
4. Restores only productive tabs - automatically filters out and skips tabs from blocked sites
5. Provides clear feedback about which blocked sites were skipped during restoration

What happens to your browser windows:

• 🔄 All browsers are completely closed - Chrome, Safari, Brave, and Comet are force-quit
• 📋 Tab URLs are saved first - using AppleScript to capture all meaningful tabs
• ⚠️ Browsers may show restore dialogs - some browsers (like Brave) may still prompt to restore tabs
• ✨ Only productive tabs return - blocked site tabs are filtered out and not reopened
• 🎯 Fresh, focused browsing - browsers open with only your work-related tabs

This ensures that:

• 🔄 No work is lost - all your productive tabs are preserved and restored
• ⚡ Blocking is immediate - browsers restart fresh and respect the hosts file
• 🎯 Clean focus - blocked site tabs aren't restored, keeping your workspace distraction-free
• 🚪 No bypass routes - browsers can't restore blocked tabs from their own tab restoration

Installation

1. Clone or download this repository:

   git clone <repository-url>
   cd focus-blocker

2. Run the installation script:

   ./install.sh

   This will:

   • Make the scripts executable
   • Install focus and unfocus commands globally
   • Set up the configuration file

3. Restart your terminal or run:

   source ~/.zshrc  # or ~/.bashrc depending on your shell

Usage

Basic Commands

• Block websites (enter focus mode):

  focus

• Block websites + launch Spotify playlist:

  focus -s                    # Launch with default playlist
  focus -s lofi               # Launch with named playlist

• Unblock websites (exit focus mode):

  unfocus

• Check status and see blocked sites:

  focus list

Managing Your Block List

• Add a site to block list:

  focus add reddit.com
  focus add youtube.com
  focus add x.com

• Remove a site from block list:

  focus remove youtube.com

• Get help:

  focus help

Managing Spotify Playlists

Focus Blocker comes with several pre-configured productivity playlists:

• deep - Deep focus music

• study - Study-friendly tracks

• coding - Programming background music

• jazz - Smooth jazz for concentration

• piano - Peaceful piano melodies

• lofi - Lo-fi hip hop beats

• nature - Nature sounds and ambient

• noise - White/brown noise for concentration

• List available playlists:

  focus playlists

• Use a specific playlist:

  focus -s deep          # Launch with deep focus music
  focus -s coding        # Launch with coding playlist
  focus -s jazz          # Launch with jazz playlist  
  focus -s nature        # Launch with nature sounds

• Add a new playlist:

  focus playlist add classical https://open.spotify.com/playlist/37i9dQZF1DWWQRwui0ExPn
  focus playlist add ambient spotify:playlist:37i9dQZF1DX0XUsuxWHRQd

• Remove a playlist:

  focus playlist remove classical

Manual Configuration

You can also manually edit the configuration file:

nano ~/repos/focus-blocker/blocked_sites.txt

Just add one domain per line (without http:// or https://).

Default Blocked Sites

The default configuration includes common distracting websites:

• Social Media: x.com, twitter.com, facebook.com, instagram.com, linkedin.com
• Entertainment: youtube.com, tiktok.com, twitch.tv
• Discussion: reddit.com, news.ycombinator.com
• Other: 9gag.com, imgur.com, pinterest.com

Examples

# Start focusing (blocks all configured sites)
$ focus
Activating focus mode...
Saving browser tabs...
✓ Saved tabs from 2 browser(s)
✓ Focus mode activated! Blocked 17 websites.
Restoring browser tabs...
  Safari: 1 tabs restored
  Brave: 2 tabs restored
✓ Restored tabs in 2 browser(s)

# Start focusing with Spotify playlist
$ focus -s coding
Activating focus mode...
Saving browser tabs...
✓ Saved tabs from 2 browser(s)
✓ Focus mode activated! Blocked 17 websites.
Restoring browser tabs...
  Safari: 1 tabs restored
  Brave: 2 tabs restored
✓ Restored tabs in 2 browser(s)
Starting Spotify...
✓ Playing: coding

# Check what's being blocked
$ focus list
Currently configured blocked sites:
  🚫 x.com (blocked)
  🚫 reddit.com (blocked)
  🚫 youtube.com (blocked)
  ...

Focus mode is currently: ACTIVE

# Manage Spotify playlists
$ focus playlists
Available Spotify playlists:
  default - spotify:playlist:37i9dQZF1DWWQRwui0ExPn
  deep - spotify:playlist:37i9dQZF1DWZeKCadgRdKQ
  study - spotify:playlist:6zCID88oNjNv9zx6puDHKj
  coding - spotify:playlist:37i9dQZF1DX5trt9i14X7j
  jazz - spotify:playlist:37i9dQZF1DWV7EzJMK2FUI
  piano - spotify:playlist:37i9dQZF1DX4sWSpwq3LiO
  lofi - spotify:playlist:37i9dQZF1DWWQRwui0ExPn
  nature - spotify:playlist:37i9dQZF1DX4PP3DA4J0N8
  noise - spotify:playlist:37i9dQZF1DWUZ5bk6qqDSy

$ focus playlist add classical https://open.spotify.com/playlist/37i9dQZF1DX4sWSpwq3LiO
✓ Added playlist 'classical' (spotify:playlist:37i9dQZF1DX4sWSpwq3LiO)

# Add a new site to block
$ focus add pinterest.com
✓ Added 'pinterest.com' to block list

# Stop focusing (unblocks all sites)
$ unfocus
Deactivating focus mode...
✓ Focus mode deactivated! All sites unblocked.

Security & Permissions

• The script requires sudo permissions to modify /etc/hosts
• A backup of your original hosts file is created automatically
• Only the Focus Blocker entries are modified; your existing hosts file content is preserved

Customization

Adding New Sites

You can add sites in several ways:

1. Command line: focus add example.com
2. Edit config file: Add domains to blocked_sites.txt
3. Bulk import: Copy a list of domains into the config file

Configuration File Location

• Blocked sites config: ~/repos/focus-blocker/blocked_sites.txt
• Spotify playlists config: ~/repos/focus-blocker/spotify_config.txt
• Backup of original hosts: ~/repos/focus-blocker/hosts_backup

Troubleshooting

Commands Not Found

If focus or unfocus commands aren't found after installation:

1. Restart your terminal
2. Check if /usr/local/bin is in your PATH
3. Run the installation script again

Permission Issues

If you get permission errors:

• Make sure you're not running as root
• The script will ask for sudo when needed
• Check that /etc/hosts is writable by root

Sites Still Accessible

If blocked sites are still accessible:

1. Check if focus mode is active: focus list
2. The script automatically restarts browsers to ensure blocking works
3. If issues persist, try manually flushing DNS cache: sudo dscacheutil -flushcache
4. Check if the site uses a different domain (like redirects)

Browser Session Issues

If browser tabs aren't being restored properly:

1. AppleScript permissions: Ensure browsers have AppleScript access permissions in System Preferences > Security & Privacy > Privacy > Automation
2. Browser force-close: The script force-quits browsers using SIGKILL to prevent auto-restoration - this is expected behavior
3. Tab storage: Tab URLs are temporarily stored in .browser_sessions/ directory and cleaned up automatically
4. Tab order: Tabs are restored in reverse order to maintain the original left-to-right arrangement

Restoring Original Hosts File

If something goes wrong, you can restore your original hosts file:

sudo cp ~/repos/focus-blocker/hosts_backup /etc/hosts
sudo dscacheutil -flushcache

Uninstallation

To remove Focus Blocker:

1. Deactivate focus mode (if active):

   unfocus

2. Remove global commands:

   sudo rm /usr/local/bin/focus /usr/local/bin/unfocus

3. Remove the project directory:

   rm -rf ~/repos/focus-blocker

Contributing

Feel free to:

• Report bugs and issues
• Suggest new features
• Submit pull requests
• Share your custom blocked sites lists

License

This project is open source and available under the MIT License.

Why Focus Blocker?

Unlike browser extensions that can be easily disabled or bypassed:

• ✅ Works across all browsers and applications
• ✅ Intelligent tab management - preserves your work while blocking distractions
• ✅ Spotify integration - launch focus sessions with productivity playlists
• ✅ Clean terminal output - informative without being overwhelming
• ✅ Harder to bypass - requires conscious effort to disable
• ✅ No browser dependencies - works even if you switch browsers
• ✅ Smart URL filtering - doesn't waste time restoring tabs from blocked sites
• ✅ Lightweight - no background processes or memory usage
• ✅ Privacy-focused - all blocking and tab management happens locally

---

Stay focused and productive! 🎯