Documentation
Schedule Claude Code or Codex to run at night
Print the launchd, cron, systemd, or Task Scheduler entry that starts a Nightshift at 04:05, after a preflight for queued work and headless permissions.
Updated
What should be checked before a run starts at 4 AM with nobody watching?
Schedule checks the things that would otherwise surprise you at 4 AM: work actually queued in the punch list, permissions that hold with nobody watching, and no second entry for the same project. Then it prints the scheduler configuration for this project and the one command that installs it. It registers nothing itself.
What the preflight checks
A scheduled start works the punch list it finds and promotes nothing, so the items must be in the list before the scheduled time. Schedule says so plainly when the list is empty and offers the ways to fill it: compose with Hunt and answer later, cut a draft, promote an imported issue, or write an item by hand.
- The agent binary, the resolved workspace, the rules file, and the generated paths.
- Permissions that hold headless: bypassPermissions or an allowlist on Claude Code, the launch grant carried in the Codex command.
- Queued work, and a warning that a parked work order is not queued work.
- A workspace with an armed or stale shift stops here; scheduling never creates the armed marker.
One generator per platform
The same verb prints the native entry for the machine that will run it and identifies the project by path, so two checkouts called api never collide. It refuses a second entry for a project that already has one, because two scheduled starts on one punch list would be two agents on one shift.
- macOS: a launchd plist.
- Linux: a crontab line, or a user .service and .timer pair with --target systemd.
- Native Windows: Task Scheduler XML with overlap prevention and a current-user interactive token.
- Codex: pass the launch command through --agent, for example codex exec -s danger-full-access.
Works with no credit left
The moment you most want to schedule a run is often the moment the quota is gone, and then no slash command works because a command is read by the model. The generator underneath is plain shell or PowerShell: it spends no tokens, needs no session, and runs from any terminal.
"$NIGHTSHIFT_PLUGIN_ROOT/runtime/ns" schedule --preflight
"$NIGHTSHIFT_PLUGIN_ROOT/runtime/ns" schedule --at 04:05
"$NIGHTSHIFT_PLUGIN_ROOT/runtime/ns" schedule --list
"$NIGHTSHIFT_PLUGIN_ROOT/runtime/ns" schedule --removeStart asks nothing
When the scheduled time arrives, Start runs one native preflight that prints one verdict per line: ok for a fact worth stating, warn for something the owner should hear while the shift still arms, and refuse for a condition that stops it. The sentences are byte-identical on POSIX and native Windows, so a headless start behaves exactly like an interactive one. Output lands in .nightshift/scheduled.log, and STOP remains the only stop a headless run can receive.
Start with a bounded prompt
This prompt names the outcome and preserves Nightshift’s review boundary. Paste it into the supported coding host from the project you want to change.
Run the Nightshift schedule preflight for this project and print the entry that starts the shift at 04:05. Do not register it.What this workflow does not claim
- The generator prints and checks; it never registers, enables, or removes a job itself.
- A sleeping or powered-off machine runs nothing; wake and login policy stay with the operating system.
Evidence and sources
These links support the released behavior, public outcomes, or problem language described on this page.
Frequently asked questions
Does Schedule register the job for me?
No. It prints the configuration and the exact install command, and it prints the command that unregisters it. Installing is the owner's action.
Will a sleeping laptop run the scheduled shift?
No. launchd defers a missed job to the next wake and cron loses it. On a Mac, pmset repeat wakeorpoweron is what makes the machine wake for it.
What happens if the punch list is empty at the scheduled time?
The start finds no work and does nothing, because a scheduled start promotes nothing. Schedule warns about that before you install the entry.