Loop
Loop sits next to Send. You write the prompt once. Nocturnal keeps sending that same message — either after each finish, or on a cadence like a recurring calendar invite, at a time you pick.
Most agent UIs can resume a chat. Loop is the part that is easy to action: a count, or every hour / every weekday, then Stop loop when you are done.
After each finish
Pick After each finish and a count (1–50). The first send is now. When that run ends on its own, the same prompt goes out again, until the count is done.
Use this for a plan you already know will walk one step at a time — “do the next item on the list” fifteen times — without sitting on Send.
The chat banner shows Looping 3 of 15. The agents list shows the same progress. Stop loop cancels what is left without killing the live run. Stop, Archive, or an error also clear the remaining repeats.
If the agent asks a question, the loop pauses until you reply. An explicit queued follow-up still runs first.
On a schedule
Pick On a schedule. Presets cover 15 minutes, 30 minutes, hour, 6 hours, day, weekdays, and week. Or set a custom every-N plus minute / hour / day / week.
Hourly jobs ask which minute — on the hour, quarter past, or any minute. Daily, weekday, weekly, and every-N-hours jobs ask what time. The first send waits for the next slot (3:07pm + every hour at :15 → 3:15pm; 4pm + every weekday at 9:00 → Monday 9:00). Minute cadences still send now, then again on the interval.
Ends After N times (1–50, including the first send) or Never — it keeps going until you tap Stop loop.
This is the monitoring job: “check the logs and tell me if anything looks off,” every hour at :00, indefinitely. Or “summarize what changed since yesterday,” every weekday at 9:00, eight times.
Nocturnal keeps the schedule on this machine, the same way it keeps ports and processes honest. It is like cron — you do not edit config files, launchd, or Task Scheduler. If Nocturnal is not running, ticks wait. After downtime, an overdue loop fires once, then jumps to now + the interval. It does not dump a backlog of missed hours.
While a run is still going (or queued), a due tick adds at most one pending copy of the prompt. A waiting question skips that beat so a pile of answers does not land when you reply. A scheduled loop that errors keeps going — a watchdog should not die on a bad hour. After-finish loops still stop on error.
Where it lives
agent.loop stores { prompt, mode, total?, remaining?, every?, unit?, weekdays?, atHour?, atMinute?, nextAt? } on the session in ~/.nocturnal/sessions.json. After-finish has no nextAt. A Never schedule omits total / remaining. A clock-aligned schedule keeps remaining at total until the first tick.
A 15s poller (agent-loops) checks nextAt. CLI and MCP use the same command.
noc agent loop -p <projectId> --prompt "Next step" --times 15
noc agent loop -s <sessionId> --prompt "Check the logs" --every 1 --unit hour --at 00:15 --forever
noc agent loop -p <projectId> --prompt "Morning recap" --every 1 --unit day --at 09:00 --weekdays --times 8
noc agent loop -s <sessionId> --stop