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
build-caffeine-exe.ps1: extracts embedded C# and compiles a standalone .exe
sign-caffeine-exe.ps1: creates/reuses a self-signed code-signing cert, optionally trusts it, and signs the .exe

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

Compile To EXE (Windows)

You can build a standalone executable from the embedded C# code in caffeine.ps1:

powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\build-caffeine-exe.ps1

Output (default):

dist\PortableCaffeine.exe

Useful options:

# Keep the extracted .cs file used for compilation
.\build-caffeine-exe.ps1 -KeepExtractedSource

# Build a console-targeted EXE instead of WinExe
.\build-caffeine-exe.ps1 -ConsoleTarget

# Custom output name/path
.\build-caffeine-exe.ps1 -OutputDir .\out -ExeName Caffeine.exe

Notes:

The build script looks for .NET Framework csc.exe on Windows (Framework64 first, then Framework).
The compiled EXE uses the same tray UI, switches, and behavior as the PowerShell-hosted version.

Self-Signed Code Signing (Dev/Test)

You can sign the compiled EXE with a locally generated self-signed code-signing certificate.

Default behavior:

Reuses an existing cert matching the configured subject (if present)
Otherwise creates a new self-signed code-signing cert
Exports the public cert to dist\PortableCaffeine-dev-signing.cer
Installs trust in CurrentUser\Root and CurrentUser\TrustedPublisher
Signs dist\PortableCaffeine.exe with Set-AuthenticodeSignature

Command:

powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\sign-caffeine-exe.ps1

Machine-wide trust (all users, requires admin):

# Run PowerShell as Administrator
.\sign-caffeine-exe.ps1 -TrustScope LocalMachine

Notes on admin requirements:

CurrentUser trust/store operations do not require admin.
LocalMachine trust (Root / TrustedPublisher) requires an elevated PowerShell session.
Creating the private key in LocalMachine\My also requires admin (-PrivateKeyStoreScope LocalMachine).

Useful options:

# Force creation of a new self-signed certificate instead of reusing an existing one
.\sign-caffeine-exe.ps1 -ForceNewCertificate

# Sign without installing trust stores (signature will be present but likely untrusted)
.\sign-caffeine-exe.ps1 -TrustScope None

# Export a PFX (password required)
.\sign-caffeine-exe.ps1 -PfxExportPath .\dist\PortableCaffeine-dev-signing.pfx -PfxPassword (Read-Host -AsSecureString)

# Use a timestamp server (optional)
.\sign-caffeine-exe.ps1 -TimestampServer http://timestamp.digicert.com

Security note:

Trusting a self-signed certificate in Root makes your machine trust anything signed by that certificate.
Use a dedicated dev/test certificate, protect the private key, and remove trust when no longer needed.
This is suitable for local/internal testing, not a substitute for a public CA-issued code-signing certificate.

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.