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:

run-caffeine.bat -showdlg -notify

Or directly:

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.exe -NoProfile -ExecutionPolicy Bypass -STA -File .\caffeine.ps1

Optional:

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

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.