From 4a8a04ecc3891dcbd2e423b2adec3a2f7281076f Mon Sep 17 00:00:00 2001 From: Corey Newton Date: Tue, 3 Feb 2026 18:13:14 -0800 Subject: [PATCH] docs(wiki): add Reminders and Idle Time --- docs/wiki/4.00-Concepts.md | 4 +- docs/wiki/4.14-How-Time-Is-Logged.md | 2 +- docs/wiki/4.16-Break-Reminders.md | 119 +++++++++++++++++++++++++++ docs/wiki/4.17-Idle-Time.md | 97 ++++++++++++++++++++++ docs/wiki/_Sidebar.md | 4 +- 5 files changed, 222 insertions(+), 4 deletions(-) create mode 100644 docs/wiki/4.16-Break-Reminders.md create mode 100644 docs/wiki/4.17-Idle-Time.md diff --git a/docs/wiki/4.00-Concepts.md b/docs/wiki/4.00-Concepts.md index 2293584e31..f305012c05 100755 --- a/docs/wiki/4.00-Concepts.md +++ b/docs/wiki/4.00-Concepts.md @@ -26,8 +26,8 @@ - [[4.05-Board-View]] - [[4.14-How-Time-Is-Logged]] - [[4.15-Timers-and-Focus-Mode]] -- Break Reminders -- Idle Time Reminders +- [[4.16-Break-Reminders]] +- [[4.17-Idle-Time]] - [[4.08-Time-Estimates]] ## Reviewing diff --git a/docs/wiki/4.14-How-Time-Is-Logged.md b/docs/wiki/4.14-How-Time-Is-Logged.md index 932f80ee8e..d69e18ca3a 100644 --- a/docs/wiki/4.14-How-Time-Is-Logged.md +++ b/docs/wiki/4.14-How-Time-Is-Logged.md @@ -36,7 +36,7 @@ When the app detects that you have been **idle** (no input for a period), it can - **Pause the current task** — The active task is cleared so time stops accruing. - **Handle the idle segment** — The time that passed while you were idle may be **removed** from the task or left for you to **reassign**. When you return, the app can show a dialog so you can assign that idle time to the same task, another task, or discard it. That keeps your log accurate and under your control. -Idle detection and the reassign dialog are configurable in [[3.02-Settings-and-Preferences]]. The important point is: the app does not silently attribute idle time to the active task; it pauses and gives you a chance to correct the log. +Idle detection and the reassign dialog are configurable in [[3.02-Settings-and-Preferences]]. The important point is: the app does not silently attribute idle time to the active task; it pauses and gives you a chance to correct the log. For a full overview of idle detection and the reassign dialog, see [[4.17-Idle-Time]]. For reminders to take breaks after sustained work time, see [[4.16-Break-Reminders]]. ## Marking Tasks Complete diff --git a/docs/wiki/4.16-Break-Reminders.md b/docs/wiki/4.16-Break-Reminders.md new file mode 100644 index 0000000000..d074e0403a --- /dev/null +++ b/docs/wiki/4.16-Break-Reminders.md @@ -0,0 +1,119 @@ +# Break Reminders + +Break reminders in Super Productivity prompt you to step away from work after you have been working for a configured amount of time without a break. They are **tied to actual time tracking**—only time when a task is actively being tracked counts toward the threshold—so the reminder reflects real work time, not just elapsed clock time. The feature exists because cognitive fatigue is often invisible, voluntary breaks are easy to skip, and long-term productivity and physical health benefit from regular pauses. Understanding what triggers break reminders, how they relate to time tracking and Focus Mode, and how you can configure or soften them helps you use them effectively. + +For how time is logged when you track a task, see [[4.14-How-Time-Is-Logged]]. For Focus Mode’s built-in breaks (e.g. Pomodoro), see [[4.15-Timers-and-Focus-Mode]]. Break reminder settings are in [[3.02-Settings-and-Preferences]]. + +## What Conditions Trigger Break Reminders? + +A break reminder is shown only when **all** of the following are true: + +1. **The feature is enabled** — Break reminders can be turned off entirely in settings. +2. **Minimum work time exceeded** — The time you have spent **working without a break** (see below) is greater than the configured minimum (default: 60 minutes). You can set a longer interval (e.g. 2 hours) if you do long deep-work sessions. +3. **Not snoozed** — You have not recently snoozed the reminder; once you snooze, the reminder stays hidden for the snooze duration (default: 15 minutes). +4. **No idle dialog** — The idle-time dialog is not currently open, so the app does not show two overlapping interruptions. + +When these conditions are met, the app shows a **banner** (and optionally a desktop notification, sound, or stronger enforcement—see below). The banner can update periodically (e.g. every minute) to reflect how long you’ve been working; desktop notifications are throttled (e.g. once per minute) to avoid notification fatigue. + +## How “Time Working Without a Break” Is Counted + +The break-reminder timer is **reset to zero** when: + +- You **mark time as a break** — For example when you use the idle dialog and assign idle time to “break,” or when you otherwise record a break. The system then assumes you took a break and starts counting work time again from zero. +- You dismiss the reminder with **“Already Did”** — You tell the app you already took a break. The timer resets and the app can add a short break (e.g. 5 minutes) to your break-time metrics, encouraging you to have actually stepped away rather than only dismissing. +- **No active task for a while** — If idle tracking is disabled, the timer can reset after a period (e.g. 10 minutes) with no task being tracked, on the assumption you may have stepped away. +- **Idle time counted as break** — If idle detection is enabled and you return from being idle and assign that time to a break, the break-reminder timer resets so you are not reminded again immediately. + +Only **time when a task is actively being tracked** (or time you manually add as “work” in certain flows) counts toward the threshold. Passive time—e.g. the app open but no task running—does not count. So the reminder is driven by **actual tracked work**, not by a simple wall-clock timer. + +## How Reminder Intervals Are Configured + +Two main time intervals are configurable: + +- **Minimum working time** — How long you must work (with a task tracked) before the first reminder appears. Default is often 1 hour; you can increase it for longer focus blocks or decrease it for more frequent nudges. +- **Snooze time** — How long the reminder stays hidden after you snooze. Default is often 15 minutes; after that, if you’re still over the minimum work time, the reminder can show again. + +You set these in the settings UI (duration inputs). The reminder message can also be customized; you can use a placeholder (e.g. `${duration}`) that the app replaces with how long you’ve been working. Optional **motivational images** can be shown with the notification to make the nudge more personal. + +## Why Breaks Are Explicitly Supported + +The app’s default message sums up the rationale: you’ve been working for a certain time without a break; stepping away (e.g. a short walk) supports **long-term productivity**. The feature exists because: + +1. **Cognitive fatigue is non-linear** — You often don’t notice when you become less effective; a nudge helps. +2. **Voluntary breaks are easy to skip** — When focused, “just one more thing” can stretch indefinitely; a reminder creates a clear boundary. +3. **Physical health** — Prolonged sitting and screen time benefit from regular interruption; the app can’t force you, but it can remind. +4. **Future vs present** — The benefits of breaks are partly in the future (health, sustained performance); reminders make that trade-off visible. + +The design is **non-punitive**: you can snooze or dismiss with “Already Did.” For users who want stronger boundaries, the app offers **escalating options** on the **desktop** (Electron) only: **lock screen** and **fullscreen blocker** (with a configurable duration). You choose how strong the nudge is—from a gentle banner to a forced pause. + +## How Break Reminders Fit Long Sessions and Sustainability + +Break reminders support **sustainable** long sessions by: + +- **Accumulating work time across the day** — The timer builds up over multiple work blocks; it doesn’t reset at noon or at session boundaries unless one of the reset conditions above applies. +- **Configurable thresholds** — You can set a longer minimum (e.g. 2 hours) so deep-work blocks are not interrupted too soon. +- **Respecting agency** — Snooze and “Already Did” let you decide when to take the break while keeping the reminder in mind. +- **Break time metrics** — When you acknowledge breaks (e.g. “Already Did”), the app can record break time so you see that you did step away. The 5-minute credit for “Already Did” is an incentive to take a real short break rather than only dismissing. + +So break reminders are both a **safety net** (don’t work for hours without a pause) and a **configurable** tool you can tune to your style. + +## Trade-offs: Uninterrupted Focus Vs Enforced Breaks + +The app balances **preserving focus** and **encouraging breaks**: + +**To preserve focus:** + +- The reminder does not show while the idle dialog is open (avoids double interruption). +- Desktop notifications are throttled so you are not spammed. +- **Snooze** lets you postpone during critical moments. +- **Configurable minimum** lets you set longer intervals for deep work. + +**To enforce breaks (optional, desktop only):** + +- **Lock screen** — The app can lock the screen until you acknowledge. +- **Fullscreen blocker** — A fullscreen overlay for a set duration. +- **Window focus** — Bring the app to the front so you see the reminder. +- **Sound** — An alert that can break through concentration. + +You choose the balance in settings: from a soft banner to a hard stop. + +## How Break Reminders Relate to Focus Mode + +Break reminders and **Focus Mode** (e.g. Pomodoro) are **separate systems** that can run at the same time: + +**Break reminders:** + +- Use **accumulated work time** across the whole day (from task tracking). +- Trigger at a **configurable interval** (e.g. 1 hour). +- Emphasize **physical health and sustained productivity**. +- You can always snooze or dismiss; they are **interruptible**. + +**Focus Mode breaks:** + +- Are part of **Pomodoro-style cycles** (e.g. 25 min work, 5 min break, long break every 4 cycles). +- Have **automatic** session/break transitions. +- Can **pause task tracking** during the break if you enable that option. +- Breaks can start automatically or manually depending on settings. + +**Focus Mode breaks do not reset the break-reminder timer by default.** So if you do a Pomodoro break, the “time working without a break” counter for break reminders keeps counting from before that break—unless you also mark that time as a break in the break-reminder sense (e.g. via idle dialog or “Already Did”). If you want Pomodoro breaks to count as “real” breaks for the reminder, you can use “Already Did” after a Pomodoro break or track idle as break when you step away. + +Together, the two systems support **both** structured work (Focus Mode) and a **safety net** when you work without Focus Mode or beyond a single Pomodoro block. + +## Idle Integration + +If **idle detection** is enabled and you **assign idle time to a break** when you return, the break-reminder timer **resets**. That avoids being reminded to take a break right after you’ve already been away (and counted that time as a break). See [[4.17-Idle-Time]] for how idle detection and the reassign dialog work. + +## Summary + +- Break reminders trigger when the feature is on, **tracked work time** exceeds the minimum, you haven’t snoozed, and the idle dialog isn’t open. +- **Only time with a task being tracked** (and certain manual work time) counts; the timer resets when you take or acknowledge a break (or after no task for a while if idle tracking is off). +- You configure **minimum work time** and **snooze time**; you can customize the message and add images. +- The feature exists to support **sustainable productivity** and health; optional **lock screen** and **fullscreen blocker** (desktop only) allow stronger enforcement. +- Break reminders are **independent of Focus Mode**; both can run together, and you can tune how much they interact (e.g. by using “Already Did” after Focus Mode breaks). + +## Related + +- [[4.14-How-Time-Is-Logged]] — How task time tracking works (break reminder counts this time) +- [[4.15-Timers-and-Focus-Mode]] — Focus Mode breaks vs break reminders +- [[4.17-Idle-Time]] — How assigning idle time to a break resets the break-reminder timer +- [[3.02-Settings-and-Preferences]] — Enable/disable, minimum time, snooze, message, lock screen, fullscreen blocker diff --git a/docs/wiki/4.17-Idle-Time.md b/docs/wiki/4.17-Idle-Time.md new file mode 100644 index 0000000000..e249b0259a --- /dev/null +++ b/docs/wiki/4.17-Idle-Time.md @@ -0,0 +1,97 @@ +# Idle Time + +Idle time in Super Productivity means **periods when the app was tracking time but you were not actively at the computer**—no keyboard or mouse input for a while. The app detects these gaps and **does not silently count them as work**. Instead, it pauses the current task (and any simple counters), removes that time from the task’s total, and when you return shows a **dialog** so you can decide how to classify the idle period: assign it to a task, to a break, or discard it. That keeps your time log accurate and gives you a conscious choice instead of inflating work time with unattended minutes. Understanding how idle is detected, how it affects logged time, and why the app surfaces it helps you use idle handling effectively. + +For how time is normally logged when you track a task, see [[4.14-How-Time-Is-Logged]]. Idle detection and the reassign dialog are configured in [[3.02-Settings-and-Preferences]]. When you assign idle time to a break, the **break reminder** timer resets; see [[4.16-Break-Reminders]]. + +## What “Idle Time” Means in Task Tracking + +**Idle time** is **system inactivity**: no keyboard or mouse input for a continuous period, measured in milliseconds. In the context of task tracking, it represents **time when the app was running and possibly tracking a task, but you were not actively working**. The app does not assume that time was “work”; it treats it as **unclassified** until you decide. So “idle” here is not “the app was idle”—it is “*you* were idle (away from the computer) while the app may have been counting time.” + +By surfacing idle time instead of ignoring it, the app **avoids inaccurate logs** (e.g. a task showing 2 hours when 30 minutes were spent away) and **makes you consciously classify** each gap. That improves both data integrity and your awareness of how time was actually spent. + +## How Idle Time Is Detected + +Idle detection depends on the environment: + +- **Desktop (Electron)** — The app uses the operating system to detect inactivity (e.g. no keyboard or mouse events). The main process **polls** at a configured interval and sends an “idle time” value to the app. When that value exceeds a **threshold** (e.g. 5 minutes by default), the app treats you as idle and triggers the idle flow. On some systems (e.g. Wayland), different methods may be used to obtain system idle time; the app chooses an available method and falls back if one fails. +- **Web** — Idle detection on the web typically **requires the Super Productivity Chrome extension**. Without it, the app cannot detect system idle time in the browser, so the feature may be unavailable or limited. +- **Android** — Idle handling may be limited; for example the idle configuration form may be hidden on Android because detection behaves differently there. + +The important point for you: when the app says you were “idle,” it means **the system reported no input for at least the configured minimum** (e.g. 5 minutes). That threshold is configurable so you can tune how sensitive the detection is. + +## Thresholds and When the Dialog Appears + +- **Minimum idle time** — You must be idle for at least this long (default: 5 minutes) before the app triggers the idle flow. Shorter absences are not treated as idle. +- **Only when a task is active** — An option (**only open idle when current task**) restricts the idle dialog to when a task is **currently being tracked**. If no task is active, the app may not show the dialog (or may handle idle differently), so you are not interrupted when you weren’t tracking anything. + +If idle detection is **disabled** in settings, the app does not run the idle flow; time is not removed or reassigned based on system idle. + +## How Idle Detection Affects Logged Time + +When the app **detects that you have become idle** (over the threshold and with tracking active, if that option is on), it: + +1. **Removes the idle duration from the current task** — The time you were away is **subtracted** from the task’s total (and per-day) time. So the task no longer includes those minutes as “work.” +2. **Stops tracking the current task** — The active task is cleared so no further time accrues until you start again or reassign. +3. **Adjusts simple counters** — If you use simple counters (e.g. habit tracking), they can be decremented for the idle duration and turned off so they don’t count the gap either. +4. **Shows the idle dialog** — When you return, the app shows a dialog with the **total time you were away**. That value is stable (e.g. based on the duration from when idle started until you returned), so you can reassign a single, clear block of time rather than a fluctuating number. + +In the dialog you can: + +- **Assign the time to a task** — Add the idle block to the same task, another task, or split it (depending on what the UI allows). Use this when you were actually working but the system didn’t see input (e.g. reading on paper). +- **Assign the time to a break** — Count the idle period as a break. This **resets the break-reminder timer** (see [[4.16-Break-Reminders]]) and records break time. +- **Discard the time** — Don’t count it as work or break; it disappears from the log. Use this when the time was not productive and you don’t want it on any task or as a break. + +So idle detection **corrects** the log by removing unattended time from the active task and then **lets you reallocate** it in a way that matches reality. + +## Why Idle Time Is Surfaced Instead of Ignored + +If the app **ignored** idle time, it would keep counting those minutes toward the active task. You’d get **inflated** task times (e.g. “2h” including 30 minutes away) and **misleading** reports and metrics. By **surfacing** idle time: + +- **Accuracy** — Only time you explicitly assign (or that wasn’t idle) stays on tasks. Unattended time is either reassigned or discarded. +- **Conscious choice** — You decide how to classify each gap: work, break, or discard. That improves both data quality and your awareness of how you spent the time. +- **Alignment with break reminders** — When you mark idle as a break, the break-reminder system knows you took a break and resets its “time without a break” counter, avoiding double-reminders. + +So idle handling is there to **improve accuracy and control**, not to punish or block you. + +## How Idle Detection Improves Accuracy + +- **Removes unattended time from active tasks and counters** — So you don’t overestimate how much you worked. +- **Uses a stable “time away” value in the dialog** — The dialog shows the total idle duration for that absence, not a jumping number, so you can reassign or discard one clear block. +- **Keeps break reminders in sync** — Assigning idle to a break updates break time and resets the break-reminder timer, so “time without a break” stays correct. + +Together, this makes your **time log reflect what actually happened**: work time, break time, and discarded time are under your control. + +## Intended User Behaviors + +The design encourages: + +- **Reviewing and categorizing idle periods** when you return — So your log stays accurate and you stay aware of gaps. +- **Using “only open when current task”** if you want the dialog only when you were tracking — So you’re not prompted when you weren’t using the app for work. + +It discourages: + +- **Leaving the app running while away** and never reviewing idle time — Which would leave the log wrong until you fix it. +- **Ignoring the dialog** and leaving large unattended blocks on tasks — Which would distort productivity metrics and reports. + +Taking a few seconds to assign or discard idle time keeps the rest of your data meaningful. + +## Platform and Configuration Notes + +- **Web** — Idle detection usually **requires the Super Productivity Chrome extension**; without it, the feature may not be available. +- **Android** — The idle configuration form may be hidden or limited because idle detection works differently on mobile. +- **Default threshold** — Often 5 minutes; you can change this in settings to be more or less sensitive. +- All idle and reassign options are in [[3.02-Settings-and-Preferences]]. + +## Summary + +- **Idle time** = system inactivity (no keyboard/mouse) for a set period; in task tracking it means “time the app might have counted but you weren’t actively there.” +- The app **detects** idle (desktop via OS; web typically via Chrome extension), **removes** that time from the active task and counters, and **shows a dialog** so you can assign it to a task, a break, or discard it. +- **Surfacing** idle time prevents inflated logs and lets you consciously classify gaps; assigning idle to a break **resets the break-reminder** timer. +- **Intended behavior**: review and categorize idle when you return; use settings to control when the dialog appears (e.g. only when a task is active) and the idle threshold. + +## Related + +- [[4.14-How-Time-Is-Logged]] — How time is normally recorded; idle is the exception that gets corrected +- [[4.16-Break-Reminders]] — Assigning idle time to a break resets the break-reminder timer +- [[3.02-Settings-and-Preferences]] — Idle detection on/off, minimum idle time, “only when current task,” and related options diff --git a/docs/wiki/_Sidebar.md b/docs/wiki/_Sidebar.md index 7f0ae28f33..e3e4a4d930 100755 --- a/docs/wiki/_Sidebar.md +++ b/docs/wiki/_Sidebar.md @@ -33,4 +33,6 @@ - [[4.12-Scheduled-Tasks]] - [[4.13-Repeating-Tasks]] - [[4.14-How-Time-Is-Logged]] -- [[4.15-Timers-and-Focus-Mode]] \ No newline at end of file +- [[4.15-Timers-and-Focus-Mode]] +- [[4.16-Break-Reminders]] +- [[4.17-Idle-Time]] \ No newline at end of file