donotsleep 0.3.0__tar.gz

donotsleep-0.3.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Bipin Subedi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

donotsleep-0.3.0/PKG-INFO

@@ -0,0 +1,140 @@
+Metadata-Version: 2.4
+Name: donotsleep
+Version: 0.3.0
+Summary: Prevent your computer from sleeping by simulating safe media key activity.
+Keywords: sleep,automation,desktop,utility,productivity
+Author: Bipin Subedi
+Author-email: Bipin Subedi <contact@bipinsubedi.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Desktop Environment
+Classifier: Topic :: Utilities
+Requires-Dist: customtkinter>=5.2.0
+Requires-Dist: pyautogui>=0.9.54
+Requires-Python: >=3.8
+Project-URL: Homepage, https://github.com/bipinsubedi/donotsleep
+Project-URL: Repository, https://github.com/bipinsubedi/donotsleep
+Project-URL: Issues, https://github.com/bipinsubedi/donotsleep/issues
+Description-Content-Type: text/markdown
+
+# donotsleep
+
+`donotsleep` is a lightweight desktop utility that helps keep your system awake by sending periodic media key events.
+
+It opens a simple GUI where you can:
+
+- Set the activity interval
+- Add randomized timing variation
+- Start/stop behavior immediately
+
+## Why This Exists
+
+Some workloads (long downloads, streaming dashboards, remote sessions, monitoring windows) are interrupted when the host device sleeps. This tool provides a minimal way to keep activity alive while you are away.
+
+## Features
+
+- GUI-first usage with instant start
+- Optional CLI interval argument
+- Randomized interval variation to reduce strict timing patterns
+- Background launch on both Windows and Linux (terminal can be closed after start)
+- Native Linux sleep inhibition (`systemd-inhibit` and `xdg-screensaver`) supporting both Wayland and X11 out of the box
+- Zero extra configuration or OS-specific settings required
+
+## Requirements
+
+- Python 3.8+
+- Windows or Linux (supports Ubuntu, Fedora, Debian, Arch, etc. under Wayland & X11)
+
+## Installation & Running
+
+### Run directly with `uvx` (no install needed)
+
+```bash
+uvx donotsleep
+```
+
+### From PyPI
+
+```bash
+pip install donotsleep
+```
+
+### Local Development
+
+```bash
+uv sync
+```
+
+## Usage
+
+### Start With Defaults (Detached in Background)
+
+```bash
+donotsleep
+```
+
+Or with `uvx`:
+
+```bash
+uvx donotsleep
+```
+
+### Start With Custom Interval
+
+```bash
+donotsleep 120
+```
+
+### Run In Foreground (debugging)
+
+```bash
+donotsleep --no-detach
+```
+
+## Behavior Notes
+
+- Default interval is `100` seconds.
+- Interval range is `10-300` seconds.
+- Randomization range is `0-20%`.
+- **Windows**: Simulates periodic `volumedown` and `volumeup` key events.
+- **Linux**: Automatically engages native system sleep inhibition (`systemd-inhibit`, `xdg-screensaver`) to prevent idle timeout, screen lock, and system sleep across both Wayland and X11 desktop sessions without requiring manual permissions. Also sends simulated media keys when supported.
+
+## Development
+
+```bash
+uv sync
+uv run donotsleep 100 --no-detach
+```
+
+## Build
+
+```bash
+uv build
+```
+
+## Publish (PyPI)
+
+```bash
+uv publish
+```
+
+## Security and Responsibility
+
+Use this tool only on systems you own or are authorized to manage. Some managed environments may restrict synthetic input automation.
+
+## License
+
+MIT License. See [LICENSE](LICENSE).

donotsleep-0.3.0/README.md

@@ -0,0 +1,108 @@
+# donotsleep
+
+`donotsleep` is a lightweight desktop utility that helps keep your system awake by sending periodic media key events.
+
+It opens a simple GUI where you can:
+
+- Set the activity interval
+- Add randomized timing variation
+- Start/stop behavior immediately
+
+## Why This Exists
+
+Some workloads (long downloads, streaming dashboards, remote sessions, monitoring windows) are interrupted when the host device sleeps. This tool provides a minimal way to keep activity alive while you are away.
+
+## Features
+
+- GUI-first usage with instant start
+- Optional CLI interval argument
+- Randomized interval variation to reduce strict timing patterns
+- Background launch on both Windows and Linux (terminal can be closed after start)
+- Native Linux sleep inhibition (`systemd-inhibit` and `xdg-screensaver`) supporting both Wayland and X11 out of the box
+- Zero extra configuration or OS-specific settings required
+
+## Requirements
+
+- Python 3.8+
+- Windows or Linux (supports Ubuntu, Fedora, Debian, Arch, etc. under Wayland & X11)
+
+## Installation & Running
+
+### Run directly with `uvx` (no install needed)
+
+```bash
+uvx donotsleep
+```
+
+### From PyPI
+
+```bash
+pip install donotsleep
+```
+
+### Local Development
+
+```bash
+uv sync
+```
+
+## Usage
+
+### Start With Defaults (Detached in Background)
+
+```bash
+donotsleep
+```
+
+Or with `uvx`:
+
+```bash
+uvx donotsleep
+```
+
+### Start With Custom Interval
+
+```bash
+donotsleep 120
+```
+
+### Run In Foreground (debugging)
+
+```bash
+donotsleep --no-detach
+```
+
+## Behavior Notes
+
+- Default interval is `100` seconds.
+- Interval range is `10-300` seconds.
+- Randomization range is `0-20%`.
+- **Windows**: Simulates periodic `volumedown` and `volumeup` key events.
+- **Linux**: Automatically engages native system sleep inhibition (`systemd-inhibit`, `xdg-screensaver`) to prevent idle timeout, screen lock, and system sleep across both Wayland and X11 desktop sessions without requiring manual permissions. Also sends simulated media keys when supported.
+
+## Development
+
+```bash
+uv sync
+uv run donotsleep 100 --no-detach
+```
+
+## Build
+
+```bash
+uv build
+```
+
+## Publish (PyPI)
+
+```bash
+uv publish
+```
+
+## Security and Responsibility
+
+Use this tool only on systems you own or are authorized to manage. Some managed environments may restrict synthetic input automation.
+
+## License
+
+MIT License. See [LICENSE](LICENSE).

donotsleep-0.3.0/pyproject.toml

@@ -0,0 +1,52 @@
+[project]
+name = "donotsleep"
+version = "0.3.0"
+description = "Prevent your computer from sleeping by simulating safe media key activity."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+keywords = [
+    "sleep",
+    "automation",
+    "desktop",
+    "utility",
+    "productivity",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: End Users/Desktop",
+    "Operating System :: Microsoft :: Windows",
+    "Operating System :: POSIX :: Linux",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.8",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Desktop Environment",
+    "Topic :: Utilities",
+]
+requires-python = ">=3.8"
+dependencies = [
+    "customtkinter>=5.2.0",
+    "pyautogui>=0.9.54",
+]
+
+[[project.authors]]
+name = "Bipin Subedi"
+email = "contact@bipinsubedi.com"
+
+[project.urls]
+Homepage = "https://github.com/bipinsubedi/donotsleep"
+Repository = "https://github.com/bipinsubedi/donotsleep"
+Issues = "https://github.com/bipinsubedi/donotsleep/issues"
+
+[project.scripts]
+donotsleep = "donotsleep.donotsleep:main"
+
+[build-system]
+requires = ["uv_build>=0.11.28,<0.15"]
+build-backend = "uv_build"

donotsleep-0.3.0/pyproject.toml.orig

@@ -0,0 +1,45 @@
+[project]
+name = "donotsleep"
+version = "0.3.0"
+description = "Prevent your computer from sleeping by simulating safe media key activity."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [
+    { name = "Bipin Subedi", email = "contact@bipinsubedi.com" }
+]
+keywords = ["sleep", "automation", "desktop", "utility", "productivity"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: End Users/Desktop",
+    "Operating System :: Microsoft :: Windows",
+    "Operating System :: POSIX :: Linux",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.8",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Desktop Environment",
+    "Topic :: Utilities",
+]
+requires-python = ">=3.8"
+dependencies = [
+    "customtkinter>=5.2.0",
+    "pyautogui>=0.9.54",
+]
+
+[project.urls]
+Homepage = "https://github.com/bipinsubedi/donotsleep"
+Repository = "https://github.com/bipinsubedi/donotsleep"
+Issues = "https://github.com/bipinsubedi/donotsleep/issues"
+
+[project.scripts]
+donotsleep = "donotsleep.donotsleep:main"
+
+[build-system]
+requires = ["uv_build>=0.11.28,<0.15"]
+build-backend = "uv_build"

donotsleep-0.3.0/src/donotsleep/__init__.py

@@ -0,0 +1,5 @@
+from .donotsleep import main, run_ui
+
+__version__ = "0.3.0"
+
+__all__ = ["run_ui", "main", "__version__"]

donotsleep-0.3.0/src/donotsleep/__main__.py

@@ -0,0 +1,4 @@
+from donotsleep.donotsleep import main
+
+if __name__ == "__main__":
+    main()

donotsleep-0.3.0/src/donotsleep/donotsleep.py

@@ -0,0 +1,398 @@
+from __future__ import annotations
+
+import argparse
+import atexit
+import ctypes
+import multiprocessing
+import os
+import random
+import shutil
+import signal
+import subprocess
+import sys
+import threading
+import time
+from pathlib import Path
+from tkinter import messagebox
+
+import customtkinter as ctk
+
+try:
+    import pyautogui
+
+    pyautogui.FAILSAFE = False
+except Exception:
+    pyautogui = None
+
+# Constants
+DEFAULT_INTERVAL = 100
+MIN_INTERVAL = 10
+MAX_INTERVAL = 300
+MAX_VARIATION = 20
+
+
+def _set_pdeathsig() -> None:
+    """Ensure child process terminates when parent process dies."""
+    try:
+        libc = ctypes.CDLL("libc.so.6")
+        PR_SET_PDEATHSIG = 1
+        libc.prctl(PR_SET_PDEATHSIG, signal.SIGTERM)
+    except Exception:
+        pass
+
+
+class LinuxSleepInhibitor:
+    """Manages system sleep inhibition on Linux via systemd-inhibit."""
+
+    def __init__(self) -> None:
+        self.process: subprocess.Popen | None = None
+        atexit.register(self.stop)
+
+    def start(self) -> None:
+        if sys.platform != "linux":
+            return
+        inhibit_bin = shutil.which("systemd-inhibit")
+        if not inhibit_bin:
+            return
+
+        for what in ("idle:sleep:handle-lid-switch", "idle:sleep"):
+            try:
+                proc = subprocess.Popen(
+                    [
+                        inhibit_bin,
+                        f"--what={what}",
+                        "--who=Do Not Sleep",
+                        "--why=Preventing sleep",
+                        "--mode=block",
+                        sys.executable,
+                        "-c",
+                        "import time; time.sleep(10**8)",
+                    ],
+                    stdout=subprocess.DEVNULL,
+                    stderr=subprocess.DEVNULL,
+                    preexec_fn=_set_pdeathsig,
+                )
+                time.sleep(0.1)
+                if proc.poll() is None:
+                    self.process = proc
+                    return
+            except Exception:
+                pass
+        self.process = None
+
+    def stop(self) -> None:
+        if self.process:
+            if self.process.poll() is None:
+                try:
+                    self.process.terminate()
+                    self.process.wait(timeout=1)
+                except Exception:
+                    try:
+                        self.process.kill()
+                    except Exception:
+                        pass
+            self.process = None
+
+
+def _simulate_activity_down() -> None:
+    """Simulate keypress or reset screensaver for volumedown."""
+    if sys.platform == "linux" and shutil.which("xdg-screensaver"):
+        try:
+            subprocess.run(["xdg-screensaver", "reset"], stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL, check=False)
+        except Exception:
+            pass
+
+    if pyautogui is not None:
+        try:
+            pyautogui.press("volumedown")
+        except Exception:
+            pass
+
+
+def _simulate_activity_up() -> None:
+    """Simulate keypress or reset screensaver for volumeup."""
+    if sys.platform == "linux" and shutil.which("xdg-screensaver"):
+        try:
+            subprocess.run(["xdg-screensaver", "reset"], stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL, check=False)
+        except Exception:
+            pass
+
+    if pyautogui is not None:
+        try:
+            pyautogui.press("volumeup")
+        except Exception:
+            pass
+
+
+def run_ui(interval: int = DEFAULT_INTERVAL) -> None:
+    """Main GUI function for Do Not Sleep settings and control."""
+    ctk.set_appearance_mode("dark")
+    ctk.set_default_color_theme("blue")
+
+    try:
+        app = ctk.CTk()
+    except Exception as e:
+        print(f"Error: Unable to initialize graphical display: {e}", file=sys.stderr)
+        return
+
+    app.title("Do Not Sleep")
+    app.geometry("500x320")
+    app.resizable(False, False)
+
+    process = None
+    worker_thread = None
+    stop_event = None
+    linux_inhibitor = None
+    initial_interval = max(MIN_INTERVAL, min(MAX_INTERVAL, int(interval)))
+
+    status_var = ctk.StringVar(value="STOPPED")
+    interval_var = ctk.DoubleVar(value=initial_interval)
+    variation_var = ctk.DoubleVar(value=10)
+    interval_display_var = ctk.StringVar(value=f"{initial_interval} s")
+    variation_display_var = ctk.StringVar(value="10%")
+
+    def terminate_worker() -> None:
+        nonlocal process, worker_thread, stop_event, linux_inhibitor
+        if sys.platform == "win32":
+            if process and process.is_alive():
+                process.terminate()
+                process.join(timeout=1)
+            process = None
+        else:
+            if stop_event:
+                stop_event.set()
+            if linux_inhibitor:
+                linux_inhibitor.stop()
+                linux_inhibitor = None
+            if worker_thread and worker_thread.is_alive():
+                worker_thread.join(timeout=1)
+            worker_thread = None
+            stop_event = None
+
+    def update_interval_display(value: float) -> None:
+        interval_display_var.set(f"{int(round(value))} s")
+
+    def update_variation_display(value: float) -> None:
+        variation_display_var.set(f"{int(round(value))}%")
+
+    def set_running_ui(running: bool) -> None:
+        if running:
+            status_var.set("RUNNING")
+            status_badge.configure(fg_color="#14532D", text_color="#D1FAE5")
+            content.configure(border_color="#22C55E")
+            primary_button.configure(text="Apply Settings")
+        else:
+            status_var.set("STOPPED")
+            status_badge.configure(fg_color="#7F1D1D", text_color="#FEE2E2")
+            content.configure(border_color="#EF4444")
+            primary_button.configure(text="Start")
+
+    def start_or_apply() -> None:
+        nonlocal process, worker_thread, stop_event, linux_inhibitor
+        new_interval = int(round(interval_var.get()))
+        variation_percent = int(round(variation_var.get()))
+
+        if new_interval < MIN_INTERVAL or new_interval > MAX_INTERVAL:
+            messagebox.showerror("Invalid Interval", f"Interval must be between {MIN_INTERVAL} and {MAX_INTERVAL} seconds.")
+            return
+        if variation_percent < 0 or variation_percent > MAX_VARIATION:
+            messagebox.showerror("Invalid Variation", f"Variation must be between 0 and {MAX_VARIATION}%.")
+            return
+
+        # Restart worker with the latest settings so slider changes can be applied at any time.
+        terminate_worker()
+        if sys.platform == "win32":
+            process = multiprocessing.Process(target=prevent_sleep, args=(new_interval, variation_percent))
+            process.start()
+        else:
+            stop_event = threading.Event()
+            linux_inhibitor = LinuxSleepInhibitor()
+            linux_inhibitor.start()
+            worker_thread = threading.Thread(
+                target=prevent_sleep,
+                args=(new_interval, variation_percent, stop_event),
+                daemon=True,
+            )
+            worker_thread.start()
+        set_running_ui(True)
+
+    def on_stop() -> None:
+        terminate_worker()
+        set_running_ui(False)
+
+    def on_close() -> None:
+        on_stop()
+        app.destroy()
+
+    app.protocol("WM_DELETE_WINDOW", on_close)
+
+    app.grid_columnconfigure(0, weight=1)
+
+    content = ctk.CTkFrame(app, border_width=2, border_color="#EF4444")
+    content.grid(row=0, column=0, padx=20, pady=20, sticky="nsew")
+    content.grid_columnconfigure(1, weight=1)
+
+    ctk.CTkLabel(content, text="Do Not Sleep", font=ctk.CTkFont(size=22, weight="bold")).grid(
+        row=0, column=0, columnspan=3, pady=(10, 16)
+    )
+
+    ctk.CTkLabel(content, text="Interval (seconds):").grid(row=1, column=0, padx=(12, 8), pady=8, sticky="w")
+    ctk.CTkSlider(
+        content,
+        from_=MIN_INTERVAL,
+        to=MAX_INTERVAL,
+        number_of_steps=MAX_INTERVAL - MIN_INTERVAL,
+        variable=interval_var,
+        command=update_interval_display,
+    ).grid(row=1, column=1, padx=8, pady=8, sticky="ew")
+    ctk.CTkLabel(content, textvariable=interval_display_var, width=50).grid(row=1, column=2, padx=(8, 12), pady=8)
+
+    ctk.CTkLabel(content, text="Randomization (%):").grid(row=2, column=0, padx=(12, 8), pady=8, sticky="w")
+    ctk.CTkSlider(
+        content,
+        from_=0,
+        to=MAX_VARIATION,
+        number_of_steps=MAX_VARIATION,
+        variable=variation_var,
+        command=update_variation_display,
+    ).grid(row=2, column=1, padx=8, pady=8, sticky="ew")
+    ctk.CTkLabel(content, textvariable=variation_display_var, width=50).grid(row=2, column=2, padx=(8, 12), pady=8)
+
+    buttons = ctk.CTkFrame(content, fg_color="transparent")
+    buttons.grid(row=3, column=0, columnspan=3, pady=(14, 8))
+    primary_button = ctk.CTkButton(buttons, text="Start", width=150, command=start_or_apply)
+    primary_button.grid(row=0, column=0, padx=8)
+    ctk.CTkButton(buttons, text="Stop", width=120, fg_color="#991B1B", hover_color="#7F1D1D", command=on_stop).grid(row=0, column=1, padx=8)
+
+    status_badge = ctk.CTkLabel(
+        content,
+        textvariable=status_var,
+        anchor="center",
+        corner_radius=10,
+        fg_color="#7F1D1D",
+        text_color="#FEE2E2",
+        width=160,
+        height=34,
+        font=ctk.CTkFont(size=14, weight="bold"),
+    )
+    status_badge.grid(row=4, column=0, columnspan=3, pady=(8, 14))
+
+    # Start immediately when the app opens using the current/default slider values.
+    start_or_apply()
+
+    app.mainloop()
+
+
+def prevent_sleep(
+    interval: int,
+    variation_percent: int,
+    stop_event: threading.Event | None = None,
+) -> None:
+    """Simulate activity by pressing volume keys and inhibiting sleep at randomized intervals."""
+    # If invoked directly (not via run_ui on Linux), manage inhibitor here
+    inhibitor = LinuxSleepInhibitor() if (sys.platform == "linux" and stop_event is None) else None
+    if inhibitor:
+        inhibitor.start()
+
+    try:
+        while True:
+            if stop_event and stop_event.is_set():
+                break
+
+            _simulate_activity_down()
+
+            if variation_percent > 0:
+                sleep_time = random.uniform(interval * (1 - variation_percent / 100), interval * (1 + variation_percent / 100))
+            else:
+                sleep_time = interval
+
+            if stop_event:
+                if stop_event.wait(sleep_time):
+                    break
+            else:
+                time.sleep(sleep_time)
+
+            if stop_event and stop_event.is_set():
+                break
+
+            _simulate_activity_up()
+
+            if variation_percent > 0:
+                sleep_time = random.uniform(interval * (1 - variation_percent / 100), interval * (1 + variation_percent / 100))
+            else:
+                sleep_time = interval
+
+            if stop_event:
+                if stop_event.wait(sleep_time):
+                    break
+            else:
+                time.sleep(sleep_time)
+    finally:
+        if inhibitor:
+            inhibitor.stop()
+
+
+def main() -> None:
+    """Entry point for the Do Not Sleep CLI tool."""
+    parser = argparse.ArgumentParser(
+        description="Do Not Sleep - Prevent sleep by pressing volume keys with randomized intervals (mutes volume to avoid buzzing)"
+    )
+    parser.add_argument(
+        "interval",
+        type=int,
+        nargs="?",
+        default=DEFAULT_INTERVAL,
+        help=f"Approximate interval in seconds between key presses (default: {DEFAULT_INTERVAL})",
+    )
+    parser.add_argument(
+        "--no-detach",
+        action="store_true",
+        help="Run GUI in the current process (useful for debugging).",
+    )
+    args = parser.parse_args()
+
+    if args.no_detach:
+        run_ui(args.interval)
+        return
+
+    # On Windows, run using pythonw in a detached process so the terminal can be closed.
+    if sys.platform == "win32":
+        python_path = Path(sys.executable)
+        pythonw_path = python_path.with_name("pythonw.exe")
+        python_exe = str(pythonw_path if pythonw_path.exists() else python_path)
+        creationflags = subprocess.DETACHED_PROCESS | subprocess.CREATE_NEW_PROCESS_GROUP
+        subprocess.Popen(
+            [python_exe, "-c", f"from donotsleep.donotsleep import run_ui; run_ui({args.interval})"],
+            creationflags=creationflags,
+            stdout=subprocess.DEVNULL,
+            stderr=subprocess.DEVNULL,
+        )
+        print("Do Not Sleep GUI started in background. It begins running immediately.")
+        return
+
+    # Non-Windows (Linux / macOS): start detached where possible.
+    env = os.environ.copy()
+    package_root = str(Path(__file__).resolve().parent.parent)
+    cur_pythonpath = env.get("PYTHONPATH", "")
+    if cur_pythonpath:
+        env["PYTHONPATH"] = f"{package_root}{os.pathsep}{cur_pythonpath}"
+    else:
+        env["PYTHONPATH"] = package_root
+
+    proc = subprocess.Popen(
+        [sys.executable, "-c", f"from donotsleep.donotsleep import run_ui; run_ui({args.interval})"],
+        stdout=subprocess.DEVNULL,
+        stderr=subprocess.DEVNULL,
+        start_new_session=True,
+        env=env,
+    )
+    try:
+        proc.wait(timeout=0.2)
+        if proc.returncode != 0:
+            print("Failed to start Do Not Sleep GUI in background. Running with --no-detach for diagnostic output:")
+            run_ui(args.interval)
+            return
+    except subprocess.TimeoutExpired:
+        pass
+
+    print("Do Not Sleep GUI started in background. It begins running immediately.")