hovancik/stretchly

Stretchly

The break time reminder app

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

Table of contents

• Install
• Default behavior
• Preferences
• Advanced Preferences
• Contributor Preferences
• Getting help
• 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

Requires macOS Ventura (13) or later.

It is recommended to install Stretchly with Homebrew tap by running the following command. See Application Signing for details.

brew install --cask hovancik/stretchly/stretchly

Note for macOS users: Homebrew recently disabled the --no-quarantine flag. As a result, macOS Gatekeeper may block the app on its first launch, showing an "unidentified developer" warning. To bypass this, go to System Settings > Privacy & Security, scroll down, and click Open Anyway next to the Stretchly alert. Alternatively, locate the app in Finder, Control-click (or Right-click) its icon, and select Open.

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

brew upgrade --cask hovancik/stretchly/stretchly

To uninstall:

brew uninstall --cask hovancik/stretchly/stretchly
brew untap hovancik/stretchly

Note: A stretchly cask also exists in the default homebrew/cask tap. It is deprecated and scheduled to be disabled on September 1, 2026 because the app is unsigned and fails Homebrew's Gatekeeper check. Until then, the bare name stretchly is ambiguous — always use the fully qualified hovancik/stretchly/stretchly to get this tap's version.

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 only ad-hoc 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

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:

• Flathub
• Snap Store

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
sudo sysctl -w kernel.apparmor_restrict_unprivileged_userns=0

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 and kernel.apparmor_restrict_unprivileged_userns=0 to /etc/sysctl.d/00-local-userns.conf and reboot.

If you're on Wayland and you would like to be able to monitor idle time, you'll need to add your user to input group, with sudo gpasswd --add $USER input (depending on your distro) and logout/login to take an effect.

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.

The regular Windows installer adds stretchly to PATH, so commands can be run from a new terminal without specifying the full executable path.

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
• longBreakAudio - 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
• trayIconStyle - icon style for menubar: default, time to break, or progress to break
• 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.

Using HTML in break ideas

You can use simple HTML formatting in custom break ideas to enhance their appearance:

Allowed HTML elements:

• <a> - links (only https:// and mailto: URLs are allowed)
• <b> - bold text
• <i> - italic text
• <br> - line breaks
• <p> - paragraphs
• <h1>, <h2>, <h3> - headings
• <img> - local images (filenames only, see below)

Using links:

"breakIdeas": [
  {
    "data": ["<b>Stretch Time!</b>", "Try this <a href=\"https://example.com/stretch\">stretching routine</a>"],
    "enabled": true
  }
]

Using local images:

Place your images in the images folder inside Stretchly's user data directory (see Preferences → About → Debug info for the exact location). Then reference them by filename only:

"breakIdeas": [
  {
    "data": ["<b>Desk Yoga</b>", "Try this pose: <img src=\"yoga-pose.png\" width=\"200\">"],
    "enabled": true
  }
]

Supported image formats: PNG, JPEG, WebP, GIF. Only images from the local images folder are allowed - remote URLs will be blocked for security.

Stretchly sanitizes all HTML to keep break windows secure by removing any unsupported tags or unsafe content.

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.

Sounds at the start of breaks

To configure the sound when a break starts, set for example "miniBreakStartSound": "crystal-glass". Same for longBreakStartSound. Built-in values: silence, crystal-glass, wind-chime, tic-toc, reverie. Setting the value to silence means no sound will be played.

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).

Custom sounds

To use your own sounds, put WAV files in the audio folder inside Stretchly's user data directory. Open it from Preferences → About by pressing Ctrl/Cmd + D and clicking audioFolder.

To replace a sound from Preferences, name your file crystal-glass.wav, wind-chime.wav, tic-toc.wav, or reverie.wav. For example, save it as crystal-glass.wav and select Crystal Glass. Stretchly will use your file whenever that sound plays, including previews. Delete the file to get the original sound back.

You can also use your own filename, for example my-sound.wav. In the preferences file, set "miniBreakAudio": "my-sound" or "longBreakAudio": "my-sound". The same works for miniBreakStartSound and longBreakStartSound. Leave out .wav in these settings. These sounds won't appear as new choices in Preferences. If you delete the file, change the setting back to a built-in sound.

Filenames can contain letters (a-z, A-Z), numbers, dots, underscores, and hyphens. Only .wav files are supported. The silence option always stays silent.

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.

You can also set naturalBreaksCheckInterval in milliseconds: how often idle time is checked. A higher number means lower CPU and energy usage, but slightly less responsive detection. Default value is 2000 which is 2 seconds.

Do Not Disturb check interval

In the preferences file, set monitorDndCheckInterval in milliseconds: how often Do Not Disturb status is checked. A higher number means lower CPU and energy usage, but slightly less responsive detection. On macOS and Linux this check can be relatively expensive, so increasing it can noticeably lower energy usage. Default value is 2000 which is 2 seconds.

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. This applies to both start and end break sounds.

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.

Manual finish break mode

If you want breaks to wait for you to finish them manually instead of automatically when the countdown reaches zero, set:

"miniBreakManualFinish": true,
"longBreakManualFinish": true

Once enabled, the break behaves normally until it reaches 100%, then the window switches to showing elapsed time since the break started. You must press the Finish button or use the endBreakShortcut to close the break.

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 durations and shortcuts

In the preferences file, set pauseBreaksDurations to define the timed options in the Pause breaks menu, in the listed order. Each entry has a duration in milliseconds and an optional global shortcut. For example, for 30 minutes and 90 minutes:

"pauseBreaksDurations": [
  { "duration": 1800000, "shortcut": "" },
  { "duration": 5400000, "shortcut": "CmdOrCtrl+Shift+P" }
]

The defaults are 30 minutes, 1 hour, 2 hours and 5 hours, with shortcuts disabled. Use positive multiples of 60000 up to 2147460000. Invalid entries are skipped; a value that isn't a list falls back to the defaults. Set [] to remove timed options and their shortcuts. Until morning and Indefinitely remain available.

Omit shortcut or set it to "" to disable it. See Electron's accelerator documentation for supported shortcuts. Shortcuts already used by other applications may be unavailable. Existing fixed-duration shortcut preferences are migrated automatically into this list.

The separate pauseBreaksUntilMorningShortcut preference sets the Until morning shortcut and defaults to "" (disabled).

Skip to the next break shortcut

In the preferences file, set skipToNextScheduledBreakShortcut, skipToNextMiniBreakShortcut, skipToNextLongBreakShortcut 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.

Reset breaks shortcut

In the preferences file, set resetBreaksShortcut 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.

Start last break again shortcut

In the preferences file, set startLastBreakAgainShortcut to your preferred value. Like the stretchly last command, it starts the last Mini or Long break again, with the same idea, even if that break was skipped or postponed. It does nothing while a break is running or breaks are paused. 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.

Appearance

In the preferences file, change themeSource: 'system' to either 'light' or 'dark' to always use the specified theme.

In the preferences file, change trayIconThemeSource: 'system' to either 'light' or 'dark' to force the tray icon's light or dark variant instead of following the system theme. On Windows, 'system' follows the Windows mode used by the taskbar. On macOS and Linux, it follows the same light/dark theme as the rest of Stretchly (the OS theme, or whatever themeSource is set to). On macOS this affects colour icons only; monochrome icons are tinted by the system.

Break window color

In the preferences file, change mainColor to whatever color you like.

Welcome window

To show the Welcome window again on the next start, change "isFirstRun" to true.

Theme transparency

To specify how solid the break window should be when Theme transparency is enabled, set the value of opacity from 0 to 1 (which is in turn 0 to 100%). If you want the break window to have a blurred background, set the value of blurredBackground to true (for macOS only).

Break window size

To specify the size of the break window, set the value of breakWindowHeight and breakWindowWidth from 0 to 0.99 (which is in turn 0 to 99% of the size of the screen). Don't set 100% as that's fullscreen.

Make Stretchly show breaks as regular windows

If you want Stretchly breaks to act as regular windows (have a titlebar, turn off always on top, be minimizable and focusable) set showBreaksAsRegularWindows to true.

Show break countdown only on one screen

By default, when breaks are shown on all screens (allScreens: true), the countdown and break idea are shown on every screen. If you'd rather keep the other screens blanked and show the countdown and idea on a single screen only, set breakContentScreen in the preferences file to one of:

• "all" - show the content on all screens (default)
• "primary" - show the content only on the primary screen
• "cursor" - show the content only on the screen where the cursor is when the break starts
• a screen index (e.g. 0, 1) - show the content only on that screen

This option has no effect when allScreens is false or when showBreaksAsRegularWindows is true. Invalid values fall back to "all".

Pause/resume breaks based on running programs

By editing appExclusions in the preferences file, you can automatically control when Stretchly breaks are paused.

To pause breaks while any of the listed programs are running, use "rule": "pause":

Linux

"appExclusions": [
    {
        "rule": "pause",
        "active": true,
        "commands": [
            "/usr/bin/vlc",
            "signal-desktop"
        ]
    }
]

Windows

"appExclusions": [
    {
        "rule": "pause",
        "active": true,
        "commands": [
            "librewolf.exe",
            "masseffectlauncher.exe"
        ]
    }
]

To allow breaks only while at least one listed program is running, use "rule": "resume". Breaks are paused when none of the listed programs are running:

Linux

"appExclusions": [
    {
        "rule": "resume",
        "active": true,
        "commands": [
            "/usr/bin/vlc",
            "signal-desktop"
        ]
    }
]

Windows

"appExclusions": [
    {
        "rule": "resume",
        "active": true,
        "commands": [
            "librewolf.exe",
            "masseffectlauncher.exe"
        ]
    }
]

You can specify multiple rules in appExclusions. Stretchly uses only the first rule marked "active": true; all later rules are ignored, even if the selected rule matches no running program. Both pause and resume rules can be present in the file, but they are not combined.

Within the selected rule, any matching entry in commands is enough. Commands should be case sensitive, but seems like this is not consistent across platforms. Therefore, sometimes, going all lowercase might be needed (this was noticed on Windows). Commands can also be substrings, meaning a rule containing "exe" will trigger when there's any running processes that contains "exe" in its name or cmd properties.

For Windows, note that paths not specified. This is because on Windows, the API we're using only checks the names of processes being run, which in the vast majority of cases is "process_name.exe". If you try to specify paths, it will not work.

You can also specify appExclusionsCheckInterval in milliseconds: lower number means more often checks, but also higher CPU usage. Default value is 2000 which is 2 seconds.

Pause breaks on Suspend/Lock

If you don't want to reset breaks once system is back from Suspend/Lock, set pauseForSuspendOrLock to false.

Monitor to show breaks on

In case you have disabled showing of breaks on all monitors, you can specify which one should contain the break window. Set screen value to one of the following:

• "primary" - primary monitor as given by OS
• "cursor" - monitor where there is cursor
• "0" (or 0), "1", "2" etc, where "0" is the first monitor returned by OS and so forth

Show current time in breaks

To show current time in breaks, set the value of currentTimeInBreaks from false to true.

To change the clock's font size, set currentTimeInBreaksFontSize to a number in pixels, for example 48. The default is 28.

To change how the time is shown, set currentTimeInBreaksFormat to a Luxon format string. The default is "tt" (localized time with seconds). For example, "cccc, D, tt" also shows the weekday and date.

Break Health Mode

Inspired by the screen-edge vignette used in video games to indicate low health, this mode adds a visual indicator around the edges of your break screen. The effect starts subtle and grows more intense each time you skip or postpone a break, and fades back down when you let breaks complete naturally. To enable it, set breakHealthMode to true.

Hide menubar/tray icon

To hide Stretchly icon in menubar/tray, set the value of showTrayIcon from true to false.

Note that this will disable graphical way of opening Stretchly Preferences. To access Preferences, you will have to use command line options (ie: stretchly preferences on Linux).

Show tray menu in Strict Mode

If you want to show tray menu even while in Strict mode, set showTrayMenuInStrictMode to true.

Show custom message in Preferences

If you want to show custom message in Preferences, set customPreferencesMessage to string of your liking.

This might be useful for corporate installations.

Disable app update functionality

If you want to disable functionality around app updates, set disableAppUpdateFeatures to true. This will make Stretchly not to check for new versions and hide related elements from the app. This value takes preference over checkNewVersion and notifyNewVersion.

This might be useful for corporate installations.

Hide location of preferences file in Debug info

If you want to hide location of preferences file in Debug info, set hidePreferencesFileLocation to true.

This might be useful for corporate installations.

Hide Strict Mode preferences

If you want to hide Strict Mode preferences section from the Preferences window, set hideStrictModePreferences to true.

This might be useful for corporate installations.

Use X11 backend on Wayland

On Linux Wayland sessions, all break windows can open on one monitor (see Known issues). If you want Stretchly to always use the X11 backend (XWayland) instead, set forceX11OnWayland to true. Stretchly will then restart itself with --ozone-platform=x11 on start, however it was launched (autostart, app menu or terminal), so you don't need to edit launcher files.

This has no effect in the Flatpak build, which already uses X11. A --ozone-platform switch on the command line is never overridden: if you start Stretchly with one, it won't restart, even with forceX11OnWayland set to true. If Stretchly starts on Wayland while this is off, it writes a note to the log about features that may not work there.

The X11 backend does not fully fix global keyboard shortcuts. On GNOME, for example, they register but only work while an X11 window has focus.

Set automatic start from congfig file

If you want autostart to work based on the value from config file, set openAtLogin.

This might be useful for corporate installations.

Contributor Preferences

Stretchly is free but you can support it by contributing code, translations or money. You will be rewarded by getting access to Contributor Preferences, ability to Sync Preferences, chat on Discord and more!

You can access contributor features after authenticating with Github or Patreon in the "Love Stretchly" section of Preferences.

Sponsoring on Github

GitHub Sponsors does not charge any fees for sponsorships from user accounts, so 100% of these sponsorships go to the sponsored developer or organization. Github Sponsors Matching Fund will also match every donation.

You will be able to access Contributor Preferences, Sync Preferences. You won't be able to chat on Discord.

Sponsoring on Patreon

Patreon has fees plus it uses PayPal, which has its fees as well.

You will be able to access Contributor Preferences, Sync Preferences and Discord chat.

Donating with Crypto currencies

Bitcoin

3EyJNtJPuQjfqP5czN88kPySwxVjv7h42y

Ethereum

0x377f05E76e96EC4C19fF225e767FeD77b1750294

Zcash

t1XyjwJtViEqATUnPKG6mdUwN4TkoCfxzcM

Let me know if you would like to use some other currency.

Currently, there are no rewards for donating with Crypto currencies, as we can't programmatically match them.

Donating with PayPal

PayPal has fees.

Currently, there are no rewards for donating via PayPal, as we can't programmatically match them.

Contributing code

By contributing code (or translations), you will be able to access Contributor Preferences, Sync Preferences. You won't be able to chat on Discord.

Getting help

For setup and usage, see the tutorial, Preferences, and Advanced Preferences.

Check Known issues and existing issues before opening a bug report or feature request. Please complete the relevant template.

For development discussions and contributions, see CONTRIBUTING.md.

Development

Feel free to join in the development of this app via Issues and Pull Requests.

Before implementing a feature, please open an Issue first, so we can be sure that no one else is working on it and that the changes will be accepted. It is important do discuss changes before implementing them (Why should we add it? How should it work? How should it look? Where will it be? ...).

Pre-requisites

• Node.js (please use version specified in package.json)
  • Linux/MacOS - you might want to use Node Version Manager to install specific version
  • Windows - download installer for specific version; during installation check “Install Additional Tools for Node.js”
• git
• Github account, if you'd like to upstream your changes

Now you can clone the repo with git clone https://github.com/hovancik/stretchly.git. Change to the new created directory and run npm i to install node packages needed. If your system is running Python 3.12 and newer, you also need to install setuptools, for example with pip install setuptools, as distutils have been deprecated.

Alternatively, open the repo in the included Dev Container (.devcontainer). It is a minimal, hardened environment (non-root user, all Linux capabilities dropped, no forwarded ports) for editing code and running tests, which makes it a good fit for LLM coding agents. It is not meant for running the Stretchly GUI.

Read on.

Debugging

You can use Stretchly's built-in debug shortcut by pressing Ctrl/Cmd + D in the About section to show information such as:

• Location of the Preferences and Log file (Clicking on file location will open it),
• Debug information for break planner

You can copy debug information to the clipboard.

If you start Stretchly in development mode with the npm run dev command, it makes it possible to debug the application in your browser on http://localhost:9222.

Logging

Stretchly uses [log](https://github.com/megahertz/electron-log) package for some extra logging. Format as following:

• System: my message for messages regarding Operating System, ie: System: resume or unlock
• Stretchly: my message for messages regarding Stretchly

Translations

You can help to translate Stretchly on Weblate. Consider joining with your Github account to be correctly credited.

Known issues

• On KDE Wayland, global shortcuts can appear configured but fail to work; see electron/electron#42573. Use the tray menu and break controls, or quit Stretchly and restart with stretchly --ozone-platform=x11.
• Windows Store build's autostart is not working, so was disabled. To use autostart, install Stretchly with the regular installer, or create a shortcut to Stretchly from shell:AppsFolder (Win+R) and move it to the shell:startup folder (Win+R).
• The Snap build may fail to start on native Wayland. Start it with the X11 backend (stretchly --ozone-platform=x11) as a workaround. See #1693.
• Wayland multi-display window placement issue puts all break windows on one monitor; start with X11 backend (stretchly --ozone-platform=x11) if needed, or set forceX11OnWayland to make Stretchly do it automatically. See electron/electron#48749.

MacOS

• users experiencing their Dock hiding after a break, requiring command + tab or a mouse click to get focus back, check System Preferences > Users & Groups > {User} > Login Items. If Hide is checked for Stretchly, uncheck it, it should solve the issue.

Windows

• users who upgraded to Windows 10 from previous Windows versions might be in "Do Not Disturb mode" all the time so they need to check "Show breaks even in Do Not Disturb mode"
• users with Chromium-based browser (Chrome, Edge, etc...) might need to set some flags when browser is non-responsive after break

Contributors

• Jan Hovancik, @hovancik, hovancik.net
• Martina Mocinecova, (pre-1.0 Stretchly logo), color schemes
• Jason Barry, @JCBarry, jcbarry.com
• Alex Alekseyenko, @alexalekseyenko
• Sean Manton, @sxmanton
• Yuriy Gromchenko, @gromchen
• Mael, @laem
• Marian Dolinský, @bramborman
• midpoint, @midpoint
• stothew, @stothew
• Zhivko Kabaivanov, @unholyHub
• sergiopjf, @sergiopjf
• William Chang, @wilicw
• Purva, @purva98
• Riddhi, @riddhi99
• Fahim Dalvi, @fdalvi, fdalvi.github.io
• Nic Desjardins, @nicdesjardins
• Vladislav Kuznecov, @fizvlad
• Oleg V., @neooleg
• Manuel Jesús Aguilera Castro, @manueljaguilera
• Ciprian Rusen, www.digitalcitizen.life
• Carlo Gandolfi, @cgand
• Kavya Jain, @kavya-jain
• Denys Otrishko, @lundibundi
• p-bo, @p-bo
• Alina Leuca, @alinaleuca
• Sabine van der Eijk, @Sabin_E
• JavaScript Joe, @jsjoeio
• Ismail Demirbilek, @dbtek
• Giacomo Rossetto, @jackymancs4
• Hum4n01d, @hum4n01d
• Ary Borenszweig, @asterite
• Jonatan Nyberg, @jony0008
• Gowee @Gowee
• William Lin, @FanciestW
• Hisman Yosika, @dnjstlr555
• Mehmet Fatih Yıldız, @mfyz
• Sunny Dhoke, @sunn-e
• Przemysław Rząd, @rzadp
• Artūras Stifanovičius, @troyanas
• pan93412, @pan93412
• robot-5, robot-5
• mfyz, mfyz
• ValarMarkhulis ValarMarkhulis
• Lucas Costi, @lucascosti
• Luke Arms, lkrms
• Chris Heyer, @cheyer
• Sheri Richardson, @sheriallis
• Florine W. Dekker, @FWDekker
• Balazs Nasz, @balazsnasz
• Daniel Bankmann, @dbankmann
• Aziks, @Aziks0
• mwoz123, @mwoz123
• pramit-marattha, @pramit-marattha
• Benedikt Allendorf, @BenediktAllendorf
• Haechan Song, @hcsong213
• Will, @qubist
• Abhilash Mandaliya, @abhilashmandaliya
• Masi, @The-Coding-Classroom
• Saksham Sharma, @ssaksham
• Jared Wood, @jwood13
• Febin Jose, @JoeNibe
• João Barreiros, @unstablectrl
• Vova Babii, @JARVIS-VOVA
• Ben Hammond, @benhamondmusic
• Jordan Williams, @jwillikers
• Nai You-Ran, @skyran1278
• Lorenzo García Rivera, @lorenzogrv, lorenzogrv.tech
• Aleh, @alehpa
• Philip Wintersteiner, @Wikiwix
• Steven Cai, @stevencaiOR
• Zhekai Jiang, @zhekai-jiang
• Bence Kovács, @githappens
• Simon R. Lincoln, @simonl65
• Florian Josef Altendorfer, @florianaltendorfer
• Ayush-kukrety, @Ayush-kukrety

Also see Github's list of contributors.

1.0 Icon and UI design by Colin Shanley (www.colinshanley.com).

Humans and Tools

• https://github.com/HatScripts/circle-flags
• https://www.icoconverter.com/ to generate .ico
• http://www.img2icnsapp.com/ to create .icns
• https://developer.microsoft.com/en-us/microsoft-edge/tools/vms/
• http://web.stanford.edu/dept/EHS/prod/general/ergo/microbreaks.html
• https://www.spineuniverse.com/wellness/ergonomics/workstation-ergonomics-take-break
• http://www.lifehack.org/articles/productivity/21-counter-intuitive-break-ideas-to-boost-your-productivity-at-work.html
• http://www.huffingtonpost.com/2012/07/24/sitting-at-work-why-its-dangerous-alternatives_n_1695618.html
• http://www.unm.edu/~lkravitz/Article%20folder/sittingUNM.html
• https://www.ninds.nih.gov/News-Events/News-and-Press-Releases/Press-Releases/Want-learn-new-skill-Take-some-short-breaks
• https://www.painscience.com/articles/chair-trouble.php
• https://www.painscience.com/articles/microbreaking.php
• https://github.com/CognirelTech/Quillpad-Server
• https://www.webmd.com/fitness-exercise/a-z/seven-minute-workout
• https://www.poetryfoundation.org/poems/57243/how-to-be-perfect
• https://justworks.com/blog/improve-mental-health-work-midday-break-ideas
• https://www.nutritiousmovement.com/dynamic-at-home-work-and-school-spaces/
• https://www.onhealth.com/content/1/eye_exercises_and_stretches
• https://www.webmd.com/pain-management/exercises-carpal-tunnel-syndrome

Sounds credits

Sounds used in this application are listed here.

• crystal glass by mlteenie, available under the Attribution License.
• wind chime by GnoteSoundz, available under the Creative Commons 0 License.
• tic toc by magundah14, available under the Creative Commons 0 License.
• silence by parcodeisuoni, available under the Attribution License.
• reverie by Seemant Chandra (instagram: piyush.x_x)

Fonts credits

This app uses Noto Sans fonts licensed under the Apache License, Version 2.0.

License

See LICENSE file.