keep-me-alive 1.0.0

A cross-platform python application to prevent your system from falling asleep.

Keep Me Alive

Prevent your computer from sleeping — effortlessly.

---

What is Keep Me Alive?

Keep Me Alive is a lightweight desktop utility that keeps your computer awake by simulating subtle activity in the background. Whether you need to prevent screen dimming during a long download, keep your messaging status "active," or avoid sleep during a presentation — Keep Me Alive has you covered.

• 🖱️ Simulates natural activity — mouse movements, clicks, key presses, or scroll events
• 🧠 Smart — only runs when you actually need it (battery, idle, app-aware)
• 🎛️ Configurable — fine-tune every parameter from a beautiful native GUI or the command line
• 💻 Cross-platform — works on macOS and Windows

---

Installation

Step 1 — Install the Backend (Required)

The core daemon is a Python package. Install it with pip:

pip install keep-me-alive

This gives you the keep-me-alive CLI and the background daemon that does the actual work. You can use it entirely from the terminal — no GUI needed.

Requires: Python 3.8+

Step 2 — Install the Desktop GUI (Optional)

For a point-and-click experience, download the companion desktop app:

Platform	Download
macOS	Download .dmg
Windows	Download .exe

The GUI is a system tray app that controls the backend visually — it will auto-detect the keep-me-alive command installed in Step 1.

After launching, Keep Me Alive appears in your system tray (menu bar on macOS). Click the icon to enable/disable, open preferences, or set a timed quit.

  

---

Features

🎯 Multiple Jiggle Styles

Style	Description
Standard	Subtle, randomized mouse movements with human-like Bézier curves
Click	Simulates left-clicks at the current cursor position
Scroll	Performs mouse wheel scrolls
Keystroke	Presses the Shift key
Mixed	Randomly combines all of the above for maximum stealth

⏱️ Smart Scheduling

• Interval — Set how often activity is simulated (5s–600s)
• Jitter — Add randomness to the interval so it feels natural (0–100%)
• Idle Timeout — Only jiggle after the system has been idle for a set duration
• Timed Quit — Automatically stop after a duration (e.g., 1h30m)

🛑 Pause When…

• Running on battery power
• The screen is locked
• Specific apps are in the foreground (e.g., pause while in Zoom)

🚀 Activate When…

• CPU usage exceeds a threshold
• Certain apps or processes are running
• A removable drive is mounted
• Media is playing

⚡ Other

• Hot-reloading — change settings without restarting the daemon
• Auto-updates — the GUI checks for new versions automatically
• Launch on Login — optionally start with your system

---

CLI Usage

The keep-me-alive command controls the background daemon.

# Start the daemon
keep-me-alive start

# Stop the daemon
keep-me-alive stop

# Toggle (start if stopped, stop if running)
keep-me-alive toggle

# Auto-quit after 1 hour and 15 minutes
keep-me-alive timed-quit 1h15m

# Cancel a timed quit
keep-me-alive cancel-quit

# Update preferences from the command line
keep-me-alive config --interval 60 --style click --distance 5

---

How It Works

Keep Me Alive has two layers:

1. Background Daemon (Python) — runs silently and performs the actual activity simulation. It monitors system state and applies your rules.
2. Desktop GUI (Electron) — a tray app that gives you one-click control and a visual preferences panel.

Both share a common configuration file (~/.keep_me_alive_config), so changes from either interface are instantly reflected.

┌─────────────────┐       ┌──────────────┐       ┌───────────────┐
│  System Tray UI │──────▶│  Config File │◀──────│  CLI Commands │
│   (Electron)    │       │  (~/.keep_   │       │  (Python/     │
│                 │       │  me_alive_   │       │   Typer)      │
└─────────────────┘       │  config)     │       └───────────────┘
                          └──────┬───────┘
                                 │ watches
                          ┌──────▼───────┐
                          │   Daemon     │
                          │  (Python)    │
                          └──────────────┘

---

Development

Prerequisites

• Python 3.8+
• Node.js & npm (for the GUI)

Setup

# Clone the repo
git clone https://github.com/amitb2050/keep-me-alive.git
cd keep-me-alive

# Install the Python package in editable mode
pip install -e .

# Install GUI dependencies
cd gui && npm install

Run Locally

# Start the CLI daemon
keep-me-alive start

# Or launch the Electron GUI in dev mode
cd gui && npm start

Run Tests

pytest

Project Structure

src/keep_me_alive/
├── core/        # Jiggler loop, OS hooks, action strategies
├── cli/         # CLI commands (Typer)
├── config/      # Pydantic settings & config management
gui/             # Electron app (HTML/CSS/JS)
tests/           # Pytest test suite

---

Contributing

Contributions are welcome! Feel free to open an issue or submit a pull request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

---

Support

If this tool saves you time, consider buying me a coffee ☕

---

License

This project is licensed under the MIT License.