oldsoul-io / headspace.spoon

Headspace

Protect your focus and keep your head in the right space by blocking distracting applications from even opening.

Controls

Headspace listens for URL schemes of the following format:

• hammerspoon://setBlacklist?tags=comma,separated,tags&apps=comma,separated,names&kill=<true or false>
• hammerspoon://setWhitelist?tags=comma,separated,tags&apps=comma,separated,names&kill=<true or false>
• hammerspoon://stopHeadspace

setBlacklist and setWhitelist are exclusive. Setting a new list will wipe out the previous settings.

If you pass kill=true in the URL, Headspace will apply your new rules to any running applications in your OSX Dock, immediately killing matching applications.

If an app is either tagged in the MacOS filesystem with a matching tag or it's name is in the apps list it will be matched and the rules applied.

MacOS doesn't let you tag built-in applications (Messages.app, Mail.app, etc.) so you can use the apps list to block them.

Optionally, if you filesystem tag an application whitelisted no rules will ever be applied to it. This is useful for things like launchers or other tools you always want available.

Usage

Using the URL scheme means that you can use any tool as your main interface for Headspace:

• Bunch has simple URL interactions.
• Shortcuts using the Open URLs action.
• Alfred Workflows
• and more!

Examples

Block distracting communications tools:
hammerspoon://setBlacklist?tags=communication,distraction&apps=Mail,Messages

Only permit applications tagged writing, and quit any other apps for a Hemingway writing session:
hammerspoon://setWhitelist?tags=writing&kill=true

Install

1. MacOS
2. Hammerspoon installed
3. Download a release to ~/.hammerspoon/Spoons/Headspace.spoon
4. Load the Spoon by adding the following code snippet to ~/.hammerspoon/init.lua:

hs.loadSpoon('Headspace'):start()

Looking for the old version?

The older version (integrated UI chooser and toggl tracker) is available for viewing here: Version 1.1.4