Focus Focus is a Mac app that helps you take back your productivity.

Focus Scripting

Customize Focus with easy scripting to match how you work.

Focus is a great help in getting work done on your Mac. You can use scripting to make Focus do even more things the way you want.

  1. Focus Workflows — Run commands on start, stop, break and unbreak
  2. URL Handlers — Interact with Focus from other apps
  3. AppleScript — Automate Focus with AppleScript

Keep reading to learn how to maximize your productivity with Focus Scripting.

Focus Workflows

Click the Focus menu icon at the top, then choose the gear icon. After that, select the Workflows tab. From here, you can run BASH scripts when you start or stop Focus, or even when you're taking a break.

Focus Workflows allow you to run special BASH commands that activate when you start or stop Focus, and when you take or end a break.

Focus Workflows allow you to run special BASH commands that activate when you start or stop Focus, and when you take or end a break.

The following environment variables are available to the scripts:

Environment Variable Description Value
FOCUS_SESSION_TYPE Type of session untimed|timed|pomodoro|schedule|break
FOCUS_SESSION_ACTIVE Session started 1|0
FOCUS_SESSION_ID Session unique ID uuid
FOCUS_SESSION_PROFILE_ID Session profile unique ID uuid
FOCUS_SESSION_PROFILE_NAME Session profile name string
FOCUS_SESSION_REFERENCE_ID Session reference unique ID uuid
FOCUS_SESSION_START_DATE Session start date date
FOCUS_SESSION_END_DATE Session end date date
FOCUS_SESSION_DURATION Session length seconds
FOCUS_SESSION_INTENDED_DURATION Session intended length seconds
FOCUS_SESSION_IS_LOCKED Session is Locked 0|1
FOCUS_SESSION_IS_EAGER Session ends when intended duration is reached 0|1
FOCUS_SESSION_IS_POMODORO Session is Pomodoro 0|1
FOCUS_SESSION_IS_SCHEDULE Session is a schedule 0|1
FOCUS_SESSION_IS_TIMER Session is timer 0|1
FOCUS_SESSION_POMODORO_SESSION_TYPE Pomodoro session type session|short-break|long-break|finished
FOCUS_SESSION_POMODORO_MAX_ROUNDS Pomodoro max rounds number
FOCUS_SESSION_TIMER_BREAKS Timer breaks 0 = breaks
1-6 = num breaks
FOCUS_SESSION_TIMER_BREAK_MINUTES Break minutes available number

URL Handlers

You can make other apps start or stop Focus by using something called URL Handlers. For instance, Focus or Unfocus in your web browser.

To turn on Focus from the command line:

open "focus://focus"

To turn off Focus:

open "focus://unfocus"

You can also start a timed Focus session

open "focus://focus?minutes=30&seconds=30"

Or just toggle between Focus and Unfocus states.

open "focus://toggle"

Importantly, if you have multiple profiles, you need to specify the profile as a parameter so Focus knows how to handle your request.

open "focus://focus?profile=Work"

Here's the full list of URLs supported by Focus:

Action Description Parameters Example
focus Start a Focus session seconds=num
unfocus Stop a Focus session profile=name focus://unfocus
toggle Toggle a Focus session profile=name focus://toggle
break Start a Break session profile=name focus://break
unbreak Stop a Break session profile=name focus://unbreak
website Add or remove a website action=add|remove
app Add or remove an application action=add|remove
preferences Show Focus preferences focus://preferences
login Login to Focus email=string
focus://[email protected]&license=123-123-123-123


AppleScript is a way to query Focus for it's current state. This is helpful when building custom productivity workflows in other apps like Alfred or Raycast.

You can use AppleScript to ask Focus what it's currently doing. This can be done through the Script Editor or another similar tool.

You can use AppleScript to ask Focus what it's currently doing. This can be done through the Script Editor or another similar tool.

Here's the full list of supported AppleScript commands

Command Description Response Type Example
is focusing Is Focus active boolean tell application "Focus" is focusing end tell
is breaking Is Focus breaking boolean tell application "Focus" is breaking end tell
is locked Is Focus locked boolean tell application "Focus" is locked end tell
active profile name Currently active profile name string tell application "Focus" active profile name end tell
profile names List of profile names string[] tell application "Focus" profile names end tell

What's Next?

Now that you've learned Focus Scripting, learn some additional features like Drag and Drop to quickly add blocked distractions, Password Mode to lock preferences, and a Global Hotkey that lets you start a Focus session from anywhere.

Need help?

Email [email protected] with any questions about Focus, and we'll assist you as soon as possible!