caffeinate-windows

Prevent Windows from sleeping - a Node.js library and CLI tool that brings macOS's caffeinate command to Windows.

Features

• ☕ Keep Windows awake without installing bloatware
• 🎯 Works with specified duration or indefinitely
• 🔧 Two methods: PowerShell (recommended) and Batch
• 📦 Small footprint, no external dependencies
• 🖥️ Works on Windows only
• ⌨️ CLI tool and programmable Node.js API

Installation

As a library (Node.js)

npm install caffeinate-windows

As a global CLI tool

npm install -g caffeinate-windows

Usage

CLI

# Keep awake indefinitely
caffeinate

# Keep awake for 1 hour (3600 seconds)
caffeinate 3600

# Keep awake for 30 minutes using PowerShell method
caffeinate 1800 powershell

# Show help
caffeinate --help

Press Ctrl+C to stop.

Node.js API

const Caffeinate = require('caffeinate-windows');

async function example() {
  const caffeinate = new Caffeinate();

  try {
    // Start caffeinating for 1 hour (duration in milliseconds)
    await caffeinate.start(3600000, { method: 'powershell' });

    console.log('Computer will stay awake');
    console.log('Is running?', caffeinate.isRunning()); // true

    // Stop whenever you want
    caffeinate.stop();
    console.log('Stopped');
    console.log('Is running?', caffeinate.isRunning()); // false

  } catch (error) {
    console.error('Error:', error.message);
  }
}

example();

TypeScript

import Caffeinate from 'caffeinate-windows';

const caffeinate = new Caffeinate();

await caffeinate.start(1800000, { method: 'powershell' });
caffeinate.stop();

API Reference

Caffeinate.start(duration?, options?)

Start preventing Windows from sleeping.

Parameters:

• duration (number, optional): Duration in milliseconds. 0 or omitted = indefinite. Default: 0
• options (object, optional):
  • method (string): 'powershell' (default, recommended) or 'batch'

Returns: Promise<void>

Throws: Error if already running or not on Windows

// Indefinite
await caffeinate.start();

// 30 minutes
await caffeinate.start(1800000);

// Using batch method
await caffeinate.start(3600000, { method: 'batch' });

Caffeinate.stop()

Stop caffeinating.

Returns: void

caffeinate.stop();

Caffeinate.isRunning()

Check if caffeinate is currently active.

Returns: boolean

if (caffeinate.isRunning()) {
  console.log('Caffeinate is active');
}

Methods

PowerShell (Recommended)

Uses Windows API (SetThreadExecutionState) to prevent sleep without side effects.

• ✅ No mouse movement
• ✅ Clean shutdown
• ✅ Works with locked screen
• ✅ Most reliable

Batch

Uses mouse movement to keep the system awake.

• ⚠️ Slightly moves mouse pointer every second
• ⚠️ May not work with locked screen
• ⚠️ Less reliable

Requirements

• Windows 7 or later
• Node.js 12+
• PowerShell (usually pre-installed)

Platform Support

Only works on Windows. Will throw an error on macOS or Linux.

const caffeinate = new Caffeinate();
await caffeinate.start(); // Throws error on non-Windows systems

License

MIT

Contributing

Contributions welcome! Please feel free to submit pull requests.

Troubleshooting

"PowerShell is not recognized"

Ensure PowerShell is installed and in your PATH. Most Windows systems have it by default.

"Caffeinate is already running"

Only one instance can run at a time. Call stop() first:

if (caffeinate.isRunning()) {
  caffeinate.stop();
}

Administrator privileges required?

No, the library works with standard user privileges.

Real-world Examples

Long download

const caffeinate = new Caffeinate();

async function downloadLargeFile() {
  // Keep awake while downloading
  await caffeinate.start();
  
  try {
    await downloadFile('large-file.zip');
  } finally {
    caffeinate.stop();
  }
}

Scheduled task

async function backupDatabase() {
  const caffeinate = new Caffeinate();
  
  // Keep awake for 2 hours during backup
  await caffeinate.start(7200000);
  
  console.log('Backing up database...');
  await database.backup();
}

Development/Testing

async function runTests() {
  const caffeinate = new Caffeinate();
  
  // Prevent sleep during long test suite
  await caffeinate.start();
  
  try {
    await runTestSuite();
  } finally {
    caffeinate.stop();
  }
}