Mindful Blocker

A lightweight /etc/hosts blocker with some love and care from Claude.

This tool is designed to be set up with Claude Code. The personalized messages are the soul of this script, and they work best when crafted through a conversation about your actual values and interests.

Why?

Most website blockers are either too easy to bypass or restrictive and emotionally cold. I'm trying to be gentle with myself and encourage healthy bedtimes and mindful, intentional browsing-- not total abstinence.

⚡ Pikachu used Rest! It's super effective! Maybe you should too.

works when it's coming from Claude. At least it does on marisa.

Features

1. Mandatory Reflection Period: Before unblocking a site, you pause for a configurable countdown (default: 60 seconds)
2. Deeply Personal Messages: During the countdown, you see messages that remind you of what you actually want to be doing - your specific books, hobbies, projects, and goals
3. Bedtime-aware: Sleep-focused messages when it's near bedtime. Have you taken the Blueprint pill yet?
4. Auto Re-blocking: Sites automatically re-block after your chosen time limit
5. Smart Configuration: Different reflection times, max durations, and time restrictions per site

Requirements

• Python 3.6+
• sudo privileges
• Claude Code for setup

macOS: Not officially supported -- I don't have an Apple device to test on. If you're on OSX, just point Claude Code at the repo and ask for OSX support. The necessary changes are probably trivial. PRs welcome!

I've only used/tested this on Ubuntu but same deal; I'd expect that Claude can easily make it support other distros.

Setup (Claude Code Required)

You need Claude Code to set this up properly.

1. Install Claude Code if you haven't already (see link above)

2. Clone this repo:

   git clone <this-repo>
   cd mindful-blocker

3. Start Claude Code and say:

   "Help me set up mindful blocker"
   

4. Claude will guide you through:

   • Asking questions about your hobbies, interests, and goals
   • Crafting 8-12 personalized zen messages based on your answers
   • Configuring which sites to block
   • Setting up reflection times and time restrictions
   • Creating your config.yaml
   • Setting up terminal aliases (critical - makes it frictionless to use!)
   • Testing that everything works

The setup conversation usually takes 5-10 minutes and is worth it - these personalized messages are what make the tool effective.

Note: Claude has access to CLAUDE_SETUP.md which contains detailed instructions on how to help you through the setup process.

How to Use It (After Setup)

Once Claude Code has helped you set up your configuration and aliases:

# Block all your configured sites
block

# Temporarily unblock a site
unblock reddit 5

If you're using Firefox (I do), due to DNS caching, you may need to do a hard refresh (ctrl+shift+r) of your reddit tab after unblocking. For the same reason, the reblock timing doesn't always work. This is a known issue.

Example session:

$ unblock reddit 5

🧘 Beginning 60-second reflection period before unblocking reddit...

   Take this time to notice:
   • What am I feeling right now?
   • What am I avoiding or seeking?
   • Is this truly what I want to do?

   🌙 The moon doesn't try to shine. It just does. Be like the moon. Go to sleep.

   ◝ 🍃 00:47 🍃 ◝

✓ Reflection period complete.
🔓 reddit is now unblocked for 5 minutes.
   Background process will reblock at 10:35 PM.

Technical Details

• No dependencies: Pure Python stdlib
• How it works: Modifies /etc/hosts to redirect sites to 127.0.0.1
• Safe: Creates automatic backup of your hosts file
• Background daemon: Auto re-blocking uses double-fork daemon process

Troubleshooting

Ask Claude Code for help! Some common issues:

• Sites still load: Clear browser DNS cache or restart browser. Also, there may be a missing domain (that needs to be blocked) from the config.
• Permission errors: Must run with sudo to modify /etc/hosts
• Config not found: Make sure you're using correct aliases or in the repo directory