# Portable Caffeine (PowerShell 5.1 + Embedded C#)

Portable Windows implementation of the Zhorn Software Caffeine utility, built as a single `caffeine.ps1` script with embedded C# (`WinForms` + Win32 API calls).

## What It Does

Prevents sleep/idle by either:

- Sending periodic key pulses (default `F15`)
- Using `SetThreadExecutionState` (`-stes`)

It also includes a tray icon app, status dialog, timers, rule-based activation, and single-instance app control commands.

## Files

- `caffeine.ps1`: main portable app
- `run-caffeine.bat`: launcher that runs with `-ExecutionPolicy Bypass -STA`

## Requirements

- Windows
- Windows PowerShell 5.1
- Desktop session (uses `System.Windows.Forms` + tray icon)

## Quick Start

Run with the batch launcher:

```bat
run-caffeine.bat -showdlg -notify
```

Or directly:

```powershell
powershell.exe -NoProfile -ExecutionPolicy Bypass -STA -File .\caffeine.ps1 -showdlg -notify
```

## Execution Policy Note

If PowerShell blocks script execution, use the launcher (`run-caffeine.bat`) or run:

```powershell
powershell.exe -NoProfile -ExecutionPolicy Bypass -STA -File .\caffeine.ps1
```

Optional:

```powershell
Unblock-File .\caffeine.ps1
```

## Supported Features / Switches

Core:

- `-on` / `-off`
- `-activefor:N`
- `-inactivefor:N`
- `-exitafter:N`
- `-lock`
- `-notify`
- `-showdlg`
- `-ontaskbar`
- `-replace`

Single-instance app commands:

- `-appexit`
- `-appon`
- `-appoff`
- `-apptoggle`
- `-apptoggleshowdlg`

Activity methods:

- Default F15 key pulse
- `-useshift`
- `-leftshift`
- `-key:NN` / `-keypress:NN`
- `-keyshift[:NN]`
- `-stes`
- `-allowss`

Conditional activation:

- `-watchwindow:TEXT`
- `-activeperiods:RANGES`
- `-activehours:RANGES` (alias)
- `-onac`
- `-cpu:N`

Tray / icon behavior:

- Custom coffee-cup tray icon (active/inactive variants)
- `-nohicon` keeps the same tray icon in both states
- Double-click tray icon toggles active/inactive

Compatibility:

- `-allowlocal` is recognized (compatibility flag)

## Examples

```bat
run-caffeine.bat -showdlg -notify
run-caffeine.bat -activefor:30
run-caffeine.bat -watchwindow:Notepad -on
run-caffeine.bat -activeperiods:08:00-12:00,13:00-17:00
run-caffeine.bat -stes -allowss
run-caffeine.bat -apptoggle
run-caffeine.bat -replace -off
```

## Notes

- This project is intended to be portable (no install required).
- The implementation targets Windows PowerShell 5.1 and Windows desktop APIs.
- Exact visual/behavioral parity with the original Zhorn Caffeine may differ slightly in some edge cases.