wakey

A lightweight CLI tool that keeps your computer awake by periodically nudging the mouse cursor a few pixels and returning it to its original position.

Why

When a machine is left idle, the OS activates a screensaver or sleep state. wakey prevents this without touching system settings — useful during long downloads, CI runs, presentations, or monitoring sessions.

Installation

npm install -g @kumar-sambhav/wakey

Or run without installing:

npx @kumar-sambhav/wakey start

Usage

wakey <command> [options]

Commands

| Command | Description | |---------|-------------| | wakey start | Start wakey as a background daemon | | wakey stop | Stop the running daemon | | wakey status | Check if wakey is running |

Options (for start)

| Flag | Description | Default | |------|-------------|---------| | --interval <n> | Seconds between nudges | 30 | | --duration <value> | Stop after this duration (e.g. 30s, 5m, 2h) | run forever | | --dry-run | Simulate nudges without moving the mouse | off |

Examples

# Start with defaults (nudge every 30 seconds)
wakey start

# Nudge every 60 seconds, stop after 2 hours
wakey start --interval 60 --duration 2h

# Dry run to verify config without moving the cursor
wakey start --interval 10 --duration 5m --dry-run

# Check if running
wakey status

# Stop the daemon
wakey stop

Logs are written to ~/.wakey/wakey.log.

macOS Note

wakey uses @computer-use/nut-js for mouse control, which requires Accessibility permissions on macOS. If the tool fails to move the mouse, go to System Settings → Privacy & Security → Accessibility and grant access to your terminal.

Development

# Run tests
npm test

# Watch mode
npm run test:watch

# Build
npm run build

Contributing

See CONTRIBUTING.md.

License

MIT