Metadata-Version: 2.4
Name: keep-me-alive
Version: 1.0.0
Summary: A cross-platform python application to prevent your system from falling asleep.
Author-email: Amit Baswa <amitb2050@gmail.com>
License: MIT
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: typer>=0.9.0
Requires-Dist: pynput>=1.7.6
Requires-Dist: psutil>=5.9.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: pydantic-settings>=2.0.0
Provides-Extra: test
Requires-Dist: pytest>=7.0.0; extra == "test"
Requires-Dist: pytest-mock>=3.10.0; extra == "test"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "test"
Requires-Dist: pytest-cov>=4.1.0; extra == "test"
Requires-Dist: ruff>=0.1.0; extra == "test"

<p align="center">
  <img src="assets/icon.png" alt="Keep Me Alive" width="128" height="128">
</p>

<h1 align="center">Keep Me Alive</h1>

<p align="center">
  <strong>Prevent your computer from sleeping — effortlessly.</strong>
</p>

<p align="center">
  <a href="https://github.com/amitb2050/keep-me-alive/releases"><img src="https://img.shields.io/github/v/release/amitb2050/keep-me-alive?label=GUI&style=flat-square&color=blue" alt="Latest Release"></a>
  <a href="https://pypi.org/project/keep-me-alive/"><img src="https://img.shields.io/pypi/v/keep-me-alive?style=flat-square&color=green" alt="PyPI Version"></a>
  <a href="https://github.com/amitb2050/keep-me-alive/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-yellow.svg?style=flat-square" alt="MIT License"></a>
  <img src="https://img.shields.io/badge/platform-macOS%20%7C%20Windows-lightgrey?style=flat-square" alt="Platform">
</p>


---

## 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:

```bash
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](https://github.com/amitb2050/keep-me-alive/releases/latest) |
| **Windows** | [Download .exe](https://github.com/amitb2050/keep-me-alive/releases/latest) |

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.

<p align="center">
  <img src="assets/screenshot-preferences.png" alt="Core Settings" width="390">&nbsp;&nbsp;
  <img src="assets/screenshot-preferences-2.png" alt="Pause & Trigger Settings" width="390">
</p>

---

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

```bash
# 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

```bash
# 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

```bash
# Start the CLI daemon
keep-me-alive start

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

### Run Tests

```bash
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 ☕

<p align="center">
  <a href="https://buymeacoffee.com/amitbaswa">
    <img src="https://img.shields.io/badge/Buy%20Me%20a%20Coffee-☕-yellow?style=for-the-badge" alt="Buy Me a Coffee">
  </a>
</p>

---

## License

This project is licensed under the [MIT License](LICENSE).
