focus-time-app

The Focus time app is a CLI tool for macOS and Windows that regularly checks your calendar for "focus time" blocker events. Whenever such events begin or end, it triggers your desktop OS's Focus Mode feature, or calls shell commands that you can configure.

It saves you from having to manually start or stop your operating system's "Do not Disturb" (focus mode/assist) mode, close/open programs, etc., whenever a focus time period begins or ends.

For now, only Outlook 365 and CalDAV calendars are supported. CalDAV support is in an early stage and may still have several problems, depending on the calendar provider/server.

Features

• Easy to set up: there is a dedicated configuration command that interactively queries all necessary information
• Various configuration settings, such as:
  • The title/subject of the focus time blocker events
  • The reminder (off, or on and the number of minutes) of the focus time blocker events. This also overwrites the reminder of existing events, which is useful if you did not create them yourself, but e.g. used Microsoft Viva Insights. NOTE: it is not recommended to use this feature for Outlook 365 calendars, because it is buggy: the Outlook platform keeps resetting the reminders once you involve an Outlook client, and once per minute, focus-time will set the reminder again, causing the Outlook client to show a reminder pop-up dialog every minute
  • List of shell commands to run when a focus time event starts or ends, including the special commands dnd-start or dnd-stop which control your operating system's Do-Not-Disturb / Focus mode
  • The Windows focus assist profile to be used ("Priority only" or "Alarms only")
• Ability to start (or stop) ad-hoc focus time sessions for a configurable duration: the tool creates a blocker event in your calendar when starting an adhoc session, or shortens the ongoing calendar event when stopping an adhoc session)

Installation

Windows (10 and newer)

• Head over to the Releases page and download the latest release for Windows
• Extract the downloaded zip archive
• Optional: move the extracted folder to a different location
• Open a CMD / PowerShell Window, navigate to the extracted folder, and call focus-time.exe configure to set up the Focus time app

macOS (12 and newer)

• Open a Terminal window, then run the following command: /usr/bin/python3 -c "$(curl -fsSL https://raw.githubusercontent.com/focus-time/focus-time-app/main/macos-installer.py)"
  • This script helps you choose an installation location, downloads the latest release and extracts it to the location. Using such a script avoids the quarantine flag that you'd get when downloading the latest release with your web browser. That quarantine flag would make it impossible to run focus-time, because it is not signed or notarized.
  • Note: you can also use this command to update an existing installation to the latest version!
• Open a Terminal Window, navigate to the installation location and call ./focus-time configure to set up the Focus time app

Usage

The Focus time app CLI comes with built-in documentation which you can access by running focus-time [command] --help. Here is a brief overview of the available commands:

• configure checks your existing configuration for validity (if there is one), or lets you create a new configuration. All configuration options are interactively prompted. It sets up a regularly-triggered background job that calls the sync command once per minute
  • If you use a personal Outlook 365 account, you can use the client ID bcc815bb-01d0-4765-ae14-e2bf0ee22445
  • If you use an Outlook 365 account for work, ask your company's Microsoft AAD admin to create a new App registration on https://portal.azure.com. The Redirect URL must be set to "Public client/native (mobile & desktop)" and point to https://focus-time.github.io/focus-time-app. Under API permissions, add Microsoft Graph permissions for Calendars.ReadWrite and offline_access. The latter permission avoids that you need to constantly re-authenticate, by providing OIDC refresh tokens that are valid for 90 days
  • Once the configuration has completed successfully, the path to the configuration file is printed to the console. You can change already-configured options there. On Windows, the file is located at C:/Users/<your-username>/AppData/Roaming/FocusTimeApp/configuration.yaml, on macOS you find it at /Users/<your-username>/Library/Application Support/FocusTimeApp/configuration.yaml
• sync Synchronizes the Do-Not-Disturb (Focus) state of your operating system with your focus time calendar events. If there is an active focus time calendar event, the Do-Not-Disturb mode (and other start commands you configured) is activated (unless this app already recently activated it). If there is no active calendar event (anymore), Do-Not-Disturb is deactivated again (if this app has set it), and other possibly configured stop commands are called. You would normally not call sync directly, because the configured background job already calls it
• start <duration in minutes> creates a new focus time calendar event in your configured calendar that starts now and ends in duration minutes. It then runs the sync command, so that your start command(s) are immediately executed
• stop stops an ongoing focus time calendar event, by shortening it so that it ends right now. Also runs the sync command internally, so that your configured stop command(s) are immediately executed.
• uninstall removes the scheduled background job (for the sync command) and Do-Not-Disturb helpers, if the operating system supports the removal
  • Note: on macOS, you have to manually open the Shortcuts app and delete the focus-time-app shortcut yourself
• version prints the version of the tool
• doctor tries to repair the scheduled background job configuration and Do-Not-Disturb helper

Contributing & troubleshooting

If you encountered a problem or have a suggestion for improving the software, please head over to the Discussions page.

Before you ask a troubleshooting question, you may first want to look at the logs stored under C:/Users/<your-username>/AppData/Roaming/FocusTimeApp/ on Windows, and under /Users/<your-username>/Library/Application Support/FocusTimeApp/ on macOS. These logs often indicate what is going wrong, providing guidance for how to fix the problem.

Roadmap

Features that are missing but will eventually be implemented can be found on the Roadmap page.

Out of scope

For the time being, the implementation of the following features is not planned (but PRs or proposals are welcome):

• Supporting other calendar providers (except for those listed on the Issues page)
• Synchronizing the state to other (mobile) devices
  • Note: macOS supports the synchronization of the Focus mode to your iPhone, out-of-the-box. For Android devices, there does not seem to be a solution, not even the Phone Link app supports it. Adding our own support would be a lot of work and require a dedicated Android companion app, and a way for the desktop CLI to wake up the device
• GUI: adding a GUI (e.g. using PySide 6) would be a lot of work, but would have the benefit of adressing a much wider audience and facilitate the usage, and have the ability to show a tray icon
• Linux support
• Offering signed binaries for macOS: we do not have an Apple developer account, nor do we intend to pay extortion money to Apple. Also, implementing automated signing+notarization of the application is not trivial

Development notes

• If you use PyCharm on Windows, in a run configuration you need to enable the checkbox Emulate terminal in output console so that retrieving passwords works properly (background)