Qwake guide

How to use Qwake on macOS, Linux, and Windows

A practical setup guide for Qwake scheduled wake calls on macOS LaunchAgent, Linux systemd with crontab fallback, and Windows Task Scheduler.

What Qwake can and cannot guarantee

Qwake sends tiny wake requests through your existing local CLI. It can verify that a scheduled attempt ran and that the provider accepted the request. It cannot guarantee provider quota refresh if the machine is off, fully asleep, offline, or rejected by the provider.

Install Qwake

npm install -g @sysiphus/qwake
qwake init
qwake doctor
qwake wake mock

One command across platforms

Qwake keeps the command surface the same across macOS, Linux, and Windows:

qwake schedule install codex claude --times 06:05,11:10,16:15,21:20
qwake schedule status
qwake schedule doctor
qwake schedule test codex claude
qwake schedule repair codex claude
qwake schedule logs
qwake schedule uninstall codex claude

macOS: LaunchAgent

On macOS, Qwake installs a LaunchAgent. This works well for laptop workflows because launchd is tied to the user session. Scheduled jobs use smart skipping by default: Qwake only calls the provider after the previous successful wake is older than the configured 5 hour window plus buffer.

launchctl list | rg qwake
cat ~/Library/LaunchAgents/com.qwake.claude.plist

Linux: systemd first, cron fallback

On Linux, Qwake first tries to install a systemd --user service and timer. If the machine does not expose systemd user services, Qwake falls back to crontab and installs equivalent daily entries automatically.

With systemd available, inspect the generated units with:

systemctl --user status qwake-claude.timer
journalctl --user -u qwake-claude.service

On cron-based machines, inspect the installed entries with:

crontab -l | grep QWAKE:claude

Windows: Task Scheduler

On Windows, Qwake installs daily tasks through schtasks. The same schedule command creates one task per time window and logs the results under ~/.qwake/logs.

where qwake
qwake schedule install codex claude --times 06:05,11:10,16:15,21:20
qwake schedule status
schtasks /Query /TN "\Qwake\claude-0605" /V /FO LIST

Troubleshooting

If a scheduled wake did not run, check these first:

qwake schedule status
qwake schedule doctor
qwake schedule test codex claude
qwake schedule logs
qwake doctor

The same log semantics apply on every platform: success, failed, limited, or skipped.