Focus is an extremely powerful productivity tool for Mac.
From blocking distracting websites and distracting applications to locking timers and schedules so they can't be stopped—Focus is an incredible productivity companion.
Focus aims to work the way you work, which is why we offer Scripting so you can integrate Focus into other applications, and other applications into Focus.
Focus Scripting enables productivity automation and is one of the most advanced ways to level up your productivity.
Why should I script Focus?
Focus Scripting lets you automate your perfect productivity environment with 1-click. Spend a little time getting it set up, and you'll reap the rewards every Focus session.
Focus is great at calling other applications, and letting other applications call it. This makes it straightforward to integrate it and create the productivity routine of your dreams.
There are two main ways to automate productivity with Focus Scripting:
- Scripting Outside Focus — call Focus from other apps
- Scripting Inside Focus — call other apps from Focus
Scripting Outside Focus
Calling Focus from other applications is easy using Apple URL Handlers.
For example, if you have Focus installed—clicking these links will start and stop Focus—from your web browser!
Here's the HTML to perform this:
<a href="focus://focus">Focus</a> or <a href="focus://unfocus">Unfocus</a>Notice instead of http:// or https:// links, they're focus:// links. This is how you call Focus from other applications.
It also works from the Terminal, turning Focus on
open "focus://focus"Turn Focus off
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 are all the commands you can use to interact with Focus from other applications:
| Action | Description | Parameters | Example |
|---|---|---|---|
| focus | Start a Focus session | seconds=num minutes=num hours=num profile=name |
focus://focus focus://focus?profile=Work focus://focus?minutes=30 |
| unfocus | Stop a Focus session | profile=name |
focus://unfocus focus://unfocus?profile=Work |
| toggle | Toggle a Focus session | profile=name |
focus://toggle focus://toggle?profile=Work |
| break | Start a Break session | profile=name |
focus://break focus://break?profile=Work |
| unbreak | Stop a Break session | profile=name |
focus://unbreak focus://unbreak?profile=Work |
| website | Add or remove a website | action=add|remove url=string profile=name |
focus://website?action=add&url=reddit.com focus://website?action=remove&url=reddit.com focus://website?action=add&url=reddit.com&profile=Work |
| app | Add or remove an application | action=add|remove path=string bundleIdentifier=string profile=name |
focus://app?action=add&path=/Applications/Discord.app focus://app?action=remove&path=/Applications/Discord.app focus://app?action=add&bundleIdentifier=com.apple.Calculator focus://app?action=add&bundleIdentifier=com.hnc.Discord&profile=Work |
| preferences | Show Focus preferences | focus://preferences | |
| login | Login to Focus | email=string license=string |
focus://[email protected]&license=123-123-123-123 |
To learn more, read Scripting Focus with URL handlers.
Note: In Ventura, Apple changed the default shell from BASH to ZSH, which means Focus URLs should be wrapped in quotes, especially when query parameters are used.
Scripting Inside Focus
To get started with Scripting inside Focus, click the Focus menubar icon, then select the Preferences icon in the window.
Click the preferences icon to customize Focus, add profiles and more!
Then select the Workflows panel from Focus Preferences, Focus should look like this:
Focus scripting can run at the start or end of a session. It can also run at the start or end of a break.
Focus Scripting lets you run any BASH command when Focus starts, stops, starts breaking or stops breaking.
This lets you play custom sounds, display notifications, hook into other apps—anything you can think of.
BASH scripting literally lets you do anything, read more to learn how.
Focus BASH Scripting
BASH scripting is a simple programming language that runs in your Terminal. Because BASH scripts can call other programming languages like C, Python, PHP, AppleScript, JavaScript and more—Focus Scripting can do literally almost anything.
To learn how to create BASH scripts for Focus, consult your favorite programmer, AI assistant or app documentation. Also, you can email [email protected] and we'll be happy to help.
Scripting Environment Variables
Every Focus BASH Script gets called with environment variables to help give you the current state of Focus.
Here they are below, you can access them like $FOCUS_ACTIVE
| 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_CURRENT_ROUND | Pomodoro round | number |
| FOCUS_SESSION_POMODORO_MAX_ROUNDS | Pomodoro max rounds | number |
| FOCUS_SESSION_TIMER_BREAKS | Timer breaks |
-1 = no breaks 0 = breaks 1-6 = num breaks |
| FOCUS_SESSION_TIMER_BREAK_MINUTES | Break minutes available | number |
Note: when spawning a new BASH shell, Focus does not include your normal bash_profile or bashrc environment. Typically specifying the full path of scripts and executables is a good way for things to work despite not being in your normal environment.
Next Up
Productivity Automation is incredibly simple, whether you're trying to create your perfect environment, or hook Focus into your existing productivity workflow—Focus Scripting has everything you need.
Now that you've learned Focus Automation, 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.