iloveitaly / hyper-focus

Block hosts, apps, specific urls (with query string vars!), launch scripts on wake, and generally optimize your productivity and focus

Hyper Focus

Hyper Focus is a command line tool that watches what you are doing on your computer and prevents you from doing distracting things.

It allows you define what "distracting things" are for you. For example, you might want to prevent yourself from using social media between 9am and 5pm. Or making certain google searches. Or using specific macOS applications. You can define what activities are distracting on a schedule.

In other words, if you are obsessive about personal productivity you can define what you want a productive day to look like and then use Hyper Focus to enforce it.

This is my first/only project in Swift, so feel to submit PRs to fix obvious things that should be better. Here's what I learned while building this project.

Why do this?

Time is the most valuable + scarce asset. Companies are incentivized to steal your time. Fight back.

• https://marco.org/2015/10/30/automatic-social-discipline
• http://mikebian.co/tag/digital-minimalism/

Installation

brew install iloveitaly/tap/hyper-focus

You can then start the service as a daemon:

brew services start iloveitaly/tap/hyper-focus

Or run it directly:

hyper-focus

# you may want to run as root if your scripts are modifying system files, like /etc/hosts
sudo hyper-focus --configuration ~/.config/focus/config.json

# for debugging/tinkering, it's helpful to tee the logs
LOG_LEVEL=debug hyper-focus 2>&1 | tee hyper-focus.log

When running via a brew service, the logs are located in $(brew --prefix)/var/log/. You can tail the logs:

tail -f $(brew --prefix)/var/log/hyper_focus.log

Or, download a release build and run it manually.

You'll need to grant accessibility permissions to the binary, which you can find via brew which hyper-focus. If scripts you have defined require root access, you'll also need to grant full disk access to the binary as well.

Running a Brew Service as Root

You may want to run Hyper Focus as root. For instance, if you are modifying the /etc/hosts file on wake, you need to run Hyper Focus as root.

Here's how to do it:

sudo brew services start iloveitaly/tap/hyper-focus

Usage

hyper-focus --help

OVERVIEW: A daemon process which helps you focus on your work.

USAGE: hyper-focus [--version] [--configuration <configuration>]

OPTIONS:
  --version               Print out the version of the application.
  -c, --configuration <configuration>
                          Path to the configuration file
  -h, --help              Show help information.

Configuration

If you are running as root, you'll want to specify the full path to any shell scripts.

Features

• Fast, CLI-oriented tool
• UI via Raycast
• Configuration in a simple JSON file (here's an example). You can add comments to this JSON!
• Very memory efficient, even over long periods of time
• No weird hangs or freezes (Focus app had this issue)
• Run scripts on sleep events (you don't need to rely on the abandoned sleepwatcher tool)
• Treat long periods of no activity as sleep, and execute relevant scripts
• Ability to run as root (if you need to modify system files, like /etc/hosts)

Sleepwatching

• Run a script on first wake of the day (custom algorithm to determine first wake)
• Treat long periods of no activity as sleep
• Run a script on each wake
• Run script as privileged in order to edit key system files like /etc/hosts

What is 'first wake'?

'First wake' means the first time the computer is woken from sleep for the current day.

Having a first wake script allows you to tie into something like clean browsers and todoist scheduler to setup your workspace and todo list for the day.

Scheduling

• Allow multiple blocking profiles that can be enabled at different times
• Ability to pause any active blocking for a period of time
• Ability to enable blocking for a period of time if no blocking is enabled

Blocking

• Block macOS applications without quitting them. This is implemented by hiding them when you switch to them.
• "Block" websites by redirecting Chrome and Safari browsers to a page of your choosing when a banned URL is encountered.
• Block hosts. Automatically adds www. variants to non-regex block hosts.
• Block specific URLs, ignoring anchors, and allowing a partial/subset match on query strings.
• Regex support

Regex

Regex support is a bit weird: add trailing and leading / to the block entry to indicate it's a regex. Think sed-style.

Example:

{
  "block_hosts": [
    // normal
    "google.com",
    // regex!
    "/.*google..*/"
  ]
}

Non-Features

• Executing scripts for other system states, like other sleep watcher tools. For instance, screen dim/wake or lid close/open.
• Kill/quit applications if they are open. This can be done via a wake script or schedule initialization script (osascript -e 'quit app "App Name"').
• Notification when a new schedule is enabled. You could do this via a schedule initialization script.
• Native macOS application.

HTTP API

Instead of UI, I've opted to a simple HTTP API that can be used to power a Raycast-based UI.

• /reload reload the configuration file without restarting the process
• /pause pause the currently running schedule
• /resume resume the currently running schedule
• /override force a blocking profile to run for a period of time
• /ping is this thing on?
• /configurations array of names of all blocking profiles. To change the order of the results, change the order of the inputs in your config file.

You can hit the API locally for testing using: http localhost:9029/status

Development

• Run the binary manually swift run
• Copy local config cp ./config.json ~/.config/focus/config.json
• Generate a new release git tag v0.1.3 && git push --tags origin HEAD

Tests

This is a fun personal tool. Tests are boring, so I didn't write many of them.

Plus, writing tests in Swift seems to be a massive pain (no dynamic mocks!).

Inspiration

• https://github.com/qiuosier/SleepTight
• https://heyfocus.com
• https://github.com/ActivityWatch/aw-watcher-window

hyper-focus's Issues

Newly opened apps don't get hidden

Simply put, if I open an app for the first time the focusedAppChanged event gets fired but the app doesn't get hidden as it should, since it looks like the event isn't propagated to focusedWindowChanged.
It works as intended if I switch away from it and then back to it, then focusedAppChanged is fired and focusedWindowChanged follows immediately, hiding the app.

My guess is that this call returns null in this circumstances, but I'm not sure why.

Problems with homebrew installation

I've tried default homebrew installation via terminal about 5 times and it displayed same error

=> swift build --disable-sandbox -c release
Last 15 lines from /Users/—/Library/Logs/Homebrew/hyper-focus/01.swift:
2023-04-01 13:36:50 +0000

swift
build
--disable-sandbox
-c
release

error: terminated(1): /usr/bin/xcrun --sdk macosx --show-sdk-platform-path output:
    xcrun: error: unable to lookup item 'PlatformPath' from command line tools installation
    xcrun: error: unable to lookup item 'PlatformPath' in SDK '/Library/Developer/CommandLineTools/SDKs/MacOSX.sdk'

config.json file does not exist

config.json file does not exist in repository.
we created our own config file to check schedule but schedule is not applying for it.

Feature request: execute script when activating schedule

First of all, thank you @iloveitaly for this little tool and its Raycast extension, this is exactly what I was looking for.

After setting up my custom config, I miss one final thing: the ability to run some "cleanup" commands when activating a schedule and maybe run another set of "restore" commands when deactivating the schedule. My actual use case for this would be to kill Slack and a few other distracting apps so they are completely removed from the dock.

Do you think this would fit the scope of this tool?