Stretchly

The break time reminder app

Stretchly is a cross-platform Electron app that reminds you to take breaks when working on your computer.

Install
Default behavior
Preferences
Advanced Preferences
Contributor Preferences
Development
Known issues
Contributors
Humans and Tools
License

Install

The latest official installers and portable versions for macOS, Windows and Linux can be found at Github Releases page. For supported versions of your OS check Electron's supported versions. Read on for details of specific OSes.

macOS

It is recommended to install Stretchly with Homebrew by running the folowing command. See Application Signing.

brew update && brew install --cask stretchly

When upgrading, run the following command. Don't forget to Quit Stretchly, first.

brew update && brew upgrade --cask

If you're using Alfred or Raycast on macOS you can use this Alfred Workflow or Raycast Extension to interact with Stretchly.

Application Signing

Stretchly is not signed (due to its costs and me not owning supported Apple device) so you will need to use a workaround for the first run. The workaround depends on if you're running an Intel or Apple Silicon chip.

Intel Chips: Open a Mac app from an unidentified developer.
Apple Chips: Open a terminal and run this command:

sudo xattr -r -d com.apple.quarantine /Applications/Stretchly.app

If you install via Homebrew, you can use the --no-quarantine flag to automatically apply the correct workaround.

brew install --cask --no-quarantine stretchly

Not sure which chip your computer has? Here's how to tell.

Windows

You can also install Stretchly with Chocolatey by running the following command from the command line or from PowerShell:

choco install stretchly

To update:

choco upgrade stretchly

Stretchly is also available in Microsoft's winget. You can install it by running:

winget install -e --id Stretchly.Stretchly

Stretchly can be also found at official Microsoft Store.

You can install Stretchly for all users silently by running this as administrator:

installer.exe /S /allusers

Linux / Portable

For portable versions and for Linux installers, head to Github Releases page. The most widely used distributions should be covered.

Stretchly is also available in some of the Linux stores:

For Debian/Ubuntu and derivates you could also try this apt repository: deb [trusted=yes] https://apt.fury.io/hovancik/ /.

Linux note

Please see http://electron.atom.io/docs/api/tray/ for Electron's Tray Linux specifics.

For Natural breaks, you might need some packages too (libxss-dev).

If Stretchly is not starting, you might need to run:

sudo sysctl kernel.unprivileged_userns_clone=1

Read more here. Depending on your distro, you probably want to do something similar to this, so the preferences are kept after reboot: Add kernel.unprivileged_userns_clone=1 to /etc/sysctl.d/00-local-userns.conf and reboot.

Running from source

To run Stretchly from source you will need Node.js, ideally the one specified in package.json. Clone the repo, run npm install and then simply run npm start to start Stretchly.

Custom installer

You can create a custom installer by running npm run pack or npm run dist after npm install --no-save.

Default behavior

When you run Stretchly for the first time, you are presented with a Welcome window that allows you to change the language, review the preferences, view the online tutorial or simply continue with the default preferences.

Stretchly itself lives in your tray, only displaying a reminder window from time to time, which contains an idea for a break.

By default, there is a 20 second Mini Break every 10 minutes and a 5 minute Long Break every 30 minutes (after 2 Mini Breaks).

You'll be notified 10 seconds before a Mini Break (and 30 seconds before a Long Break) so that you can prepare to pause your work.

When a break starts, you can postpone it once for 2 minutes (Mini Breaks) or 5 minutes (Long Breaks). Then, after a specific time interval passes, you can skip the break. Both actions are available by clicking on the link at the bottom of window or by using the Ctrl/Cmd + X keyboard shortcut.

Clicking the Stretchly icon in your tray area will display the current status of breaks, provide menu items with extra functionality, and link to the Preferences.

Stretchly is monitoring your idle time, so when you are idle for 5 minutes, breaks will be paused until you return.

Stretchly is also monitoring Do Not Disturb mode, so breaks are paused when DnD mode is On.

Stretchly follows the theme of your system and is also available in dark mode.

Interact with stretchly from command line

When a Stretchly instance is running, the stretchly command can be use to interact with it from the command line.

Type stretchly help to get a list of all commands and options available as well as some examples.

Preferences

Most of the preferences can be customized by clicking on the "Preferences" item in the tray menu. (On Windows, to open Preferences, you can also double-click on the tray icon.)

Preferences are divided into multiple categories and you are encouraged to take some time to make Stretchly your own by customizing them.

You can also Restore the defaults to return to the default preferences state.

Advanced Preferences

While the most of the preferences can be edited via the app, some options and values are not available to make the app easy to understand and setup.

All preferences are saved in a JSON file, so you can set Stretchly in the way you need. Use the Ctrl/Cmd + D shortcut while viewing the About section of Preferences, to show debug info and display a clickable link to the preferences file.

It's recommended to Quit Stretchly before editing the preferences file.

To make sure that all works as expected, it's always good idea to check that format of the preferences file is correct, ie. by using jsonformatter.

After you make changes to preferences files, some of the values being shown in Preferences or elsewhere might show incorrect value, as the UI is expecting specific values and is not handling cases where user makes manual changes to preferences file.

Some of the extra preferences are available in Contributor Preferences for Contributors. Those are marked by badge.

Preferences marked with might not work correctly and might break Stretchly. Use at own risk.

Note: Before 1.0, Mini Breaks and Long Breaks were called Microbreaks and Breaks, respectively. To keep the upgrade smooth they still use that name in preferences file and in code.

Preferences editable in the app

Here are the preferences editable via the app. If values in the app does not suite your style, you could edit them maually:

microbreakDuration - duration of Mini Break (ms)
microbreakInterval - interval of Mini Break (ms)
breakDuration - duration of Long Break (ms)
breakInterval - interval of Long Break (Mini Breaks)
breakNotification - show notification before Mini Break
microbreakNotification - show notification before Long Break
microbreak - enable Mini Breaks
break - enable Long Breaks
microbreakStrictMode - enable strict mode for Mini Breaks
breakStrictMode - enable strict mode for Long Breaks
mainColor - theme color code (for Long Breaks),
miniBreakColor - theme color code (for Mini Breaks),
transparentMode - show break windows as transparent
audio - sound theme name (for Long Breaks)
miniBreakAudio - sound theme name (for Mini Breaks)
fullscreen - show breaks in fullscreen mode
ideas - show break ideas
naturalBreaks - monitor idle time
allScreens - show breaks on all screens
language - language
useMonochromeTrayIcon - use monochrome icon
useMonochromeInvertedTrayIcon - use inverted monochrome icon
silentNotifications - enable sounds
monitorDnd - monitor DND mode
checkNewVersion - check for new versions

Editing Break ideas

In the preferences file, change useIdeasFromSettings: false, to useIdeasFromSettings: true, and edit breakIdeas and microbreakIdeas.

Note that when a new Stretchly version with new break ideas is out, your custom ideas will not be overwritten. You can reset break ideas to the latest defaults when you "Restore defaults" from Preferences window.

Editing Break notification interval

In the preferences file, change breakNotificationInterval: 30000, to whatever value you want. 30000 is 30 seconds. Same goes for Mini Breaks.

Editing sunrise time to pause breaks until morning

In the preferences file you can set the morningHour setting to pause until that hour today or the next day Otherwise, you can set morningHour: "sunrise" and set posLatitude, posLongitude in preferences to pause until the actual sunrise in your area. E.g. if you live in Boston you would set: morningHour: "sunrise", posLatitude: 42.3, posLongitude: 71

Editing postpone functionality

In the preferences file, you can edit microbreakPostpone and breakPostpone to enable or disable the ability to postpone breaks, microbreakPostponeTime and breakPostponeTime to change the postpone time in milliseconds, microbreakPostponesLimit and breakPostponesLimit to change the number of allowed postpones per break, and finally, microbreakPostponableDurationPercent and breakPostponableDurationPercent to change the percentage of the break during which the user can postpone it.

New version notification

In the preferences file, set notifyNewVersion: false, to disable new version notification.

Play sound at the start of the Break

In the preferences file, set microbreakStartSoundPlaying: true, to start a Mini Break with a sound (The same sound will be played as at the end of the break). Same for breakStartSoundPlaying.

Different sound for Mini and Long breaks

To play different sound for Mini Breaks, set miniBreakAudio to desired value (crystal-glass, silence, tic-toc, wind-chime).

Different color theme for Mini and Long breaks

To have different theme for Mini Breaks, set miniBreakColor to desired value, ie #123456.

Natural breaks inactivity time

In the preferences file, set naturalBreaksInactivityResetTime to your preferred value (in milliseconds greater than than 20000ms). This is an idle time length, after which Stretchly breaks will be paused until the user resumes activity.

Volume for break sounds

In the preferences file, set volume to your preferred value. Default value is 1, which is 100% volume. Set it, for example, to 0.61 for 61% volume.

Postpone/Finish Break Shortcut

In the preferences file, set endBreakShortcut to your preferred value. We do not validate this input, so please check Electron's documentation for available values for key and modifier. When a given accelerator is already taken by other applications, this call will silently fail. This behavior is intended by operating systems, since they don't want applications to fight for global shortcuts.

If you'd like to disable the shortcut, set value to empty string "".

Default value is CmdOrCtrl+X.

Toggle Breaks Shortcut

Toggling between Pause Breaks and running breaks.

In the preferences file, set pauseBreaksToggleShortcut to your preferred value. We do not validate this input, so please check Electron's documentation for available values for key and modifier. When a given accelerator is already taken by other applications, this call will silently fail. This behavior is intended by operating systems, since they don't want applications to fight for global shortcuts.

If you'd like to disable the shortcut, set value to empty string "". That's the default value as well.

Pause Breaks for Duration Shortcuts

You can also set shortcuts to pause breaks for a specific duration by modifying the following values in the preferences file:

pauseBreaksFor30MinutesShortcut
pauseBreaksFor1HourShortcut
pauseBreaksFor2HoursShortcut
pauseBreaksFor5HoursShortcut
pauseBreaksUntilMorningShortcut

If you'd like to disable the shortcuts, set value to empty string "". That's the default value as well.

Skip to the next Break Shortcut

In the preferences file, set skipToNextScheduledBreakShortcut, skipToNextMiniBreakShortcut, skipToNextLongBreakShortcut to your preferred value. We do not validate