Qwake guide

How to use Qwake on macOS, Linux, and Windows

A practical setup guide for Qwake scheduled wake calls on macOS LaunchAgent, Linux cron/systemd, 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

macOS: LaunchAgent, recommended

The built-in scheduler installer currently targets macOS LaunchAgent. It is better than cron for laptop workflows because launchd integrates with user sessions. 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.

qwake schedule install claude --times 06:05,11:10,16:15,21:20
qwake schedule status claude
qwake schedule run claude
qwake schedule logs claude

You can tune the guard with --window-minutes 300 --buffer-minutes 5, or disable it with --no-smart if you intentionally want every scheduled time to call the provider.

Healthy logs look like this:

[2026-06-01 09:20:00 +08:00] wake agent=claude status=success exitCode=0 limited=false durationMs=1842 utc=2026-06-01T01:20:00.000Z
[2026-06-01 11:10:00 +08:00] wake agent=claude status=skipped exitCode=0 limited=false durationMs=3 utc=2026-06-01T03:10:00.000Z nextWakeAt=2026-06-01T06:25:00.000Z

schedule run asks launchd to trigger the installed job once, so you can verify the real scheduled path without waiting for the next clock time. On MacBooks, jobs may still run after the lid is closed if macOS has not reached deep sleep, briefly wakes, or is connected to power. Use the log timestamp as the practical source of truth.

For low-level launchd inspection:

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

Uninstall:

qwake schedule uninstall claude

Linux: cron or systemd timer

Qwake does not yet install Linux schedules automatically. Use cron for a simple setup, or a systemd user timer if you want stronger observability.

# cron
5 6 * * * qwake wake claude --smart >> ~/.qwake/logs/claude.log 2>> ~/.qwake/logs/claude.error.log
10 11 * * * qwake wake claude --smart >> ~/.qwake/logs/claude.log 2>> ~/.qwake/logs/claude.error.log
15 16 * * * qwake wake claude --smart >> ~/.qwake/logs/claude.log 2>> ~/.qwake/logs/claude.error.log
20 21 * * * qwake wake claude --smart >> ~/.qwake/logs/claude.log 2>> ~/.qwake/logs/claude.error.log

With systemd user timers, run the same command from a user service and inspect it with:

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

Windows: Task Scheduler

Qwake does not yet install Windows schedules automatically. After installing with npm, Windows usually creates command shims such as qwake.cmd and qwake.ps1 in your npm global bin directory. Find the exact path with:

where qwake
qwake doctor
qwake wake claude --smart

If where qwake prints a path ending in qwake.cmd, you can point Task Scheduler directly at that file. A wrapper batch file is often easier to debug because you control the log path. Create %USERPROFILE%\qwake-claude.bat:

@echo off
set QWAKE_LOG_DIR=%USERPROFILE%\.qwake\logs
if not exist "%QWAKE_LOG_DIR%" mkdir "%QWAKE_LOG_DIR%"
qwake wake claude --smart >> "%QWAKE_LOG_DIR%\claude.log" 2>> "%QWAKE_LOG_DIR%\claude.error.log"

Task Scheduler GUI settings:

Create Task, not Basic Task, so multiple triggers are easier to manage.
Triggers: add four daily triggers at 06:05, 11:10, 16:15, and 21:20. This is the fixed-time workflow that pairs well with smart mode.
Action: start a program.
Program/script: %USERPROFILE%\qwake-claude.bat.
Start in: %USERPROFILE%.
Conditions: enable “Wake the computer to run this task” if you want Windows to try waking from sleep.

If you prefer a pure command-line setup, create four tasks with schtasks:

schtasks /Create /TN "Qwake Claude 0605" /SC DAILY /ST 06:05 /TR "%USERPROFILE%\qwake-claude.bat" /F
schtasks /Create /TN "Qwake Claude 1110" /SC DAILY /ST 11:10 /TR "%USERPROFILE%\qwake-claude.bat" /F
schtasks /Create /TN "Qwake Claude 1615" /SC DAILY /ST 16:15 /TR "%USERPROFILE%\qwake-claude.bat" /F
schtasks /Create /TN "Qwake Claude 2120" /SC DAILY /ST 21:20 /TR "%USERPROFILE%\qwake-claude.bat" /F

Another valid pattern is interval-based scheduling, for example every 5 hours. This is less aligned with fixed workday windows, but smart mode makes it safe because redundant runs are skipped:

schtasks /Create /TN "Qwake Claude Every 5h" /SC HOURLY /MO 5 /TR "%USERPROFILE%\qwake-claude.bat" /F

Verify later with:

type "%USERPROFILE%\.qwake\logs\claude.log"
type "%USERPROFILE%\.qwake\logs\claude.error.log"
schtasks /Query /TN "Qwake Claude 0605" /V /FO LIST

Troubleshooting

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

qwake schedule status claude
qwake schedule run claude
qwake schedule logs claude
qwake doctor

On macOS with nvm, older schedules may fail with env: node: No such file or directory. Reinstall the schedule with the latest Qwake so LaunchAgent uses the absolute Node path.