Command Code

Repeat a task with /loop

/loop runs a task now and runs it again later, in the same conversation, until you stop it or the task decides another check is pointless. Give it an interval and it runs on that cadence. Leave the interval out and Command Code picks the next delay itself after every check.

It is for work that needs watching rather than building. "Check the deploy every 5 minutes." "Watch this pull request until CI is green." "Poll the migration until it finishes." If you want the agent to build toward something, use /goal instead.

/loop is a bundled skill on top of the scheduler. It shows up in the slash menu, and the cadence and task are parsed by code, so the model never has to guess the schedule.

Usage

Basic usage

/loop <interval> <task> # Run now, then repeat on a fixed interval /loop <task> # Run now, then self-pace the next checks /loop <task> every <interval> # Same as a fixed loop, interval at the end /loop <interval> # Run the default loop task on a fixed interval /loop # Run the default loop task, self-paced
InvocationBehavior
/loop 5m check the deployRuns the task now, then every five minutes.
/loop check the deploy every 2 hoursSame thing, with the cadence written at the end of the task.
/loop check the deployRuns now, then picks the next delay after every check.
/loop 15mRuns the default loop task now and every 15 minutes.
/loopRuns the default loop task now, self-paced.

How it works

  1. The task runs once, immediately, in the current turn. Nobody waits for the first interval to pass.
  2. A scheduled task is created. A fixed loop becomes a recurring task in the conversation. A self-paced loop becomes a single pending wakeup, and each iteration replaces it.
  3. When the schedule fires, the task text reaches the agent fenced as data. It cannot override higher-priority instructions or widen permission for destructive or external actions. Tool calls inside an iteration still go through your normal permission mode.
  4. The loop ends when the work is done or you stop it. A self-paced loop can stop itself. A fixed loop keeps firing until you cancel it or it hits its seven-day lifetime.
Info

Only a /loop you type starts a self-paced loop. Ask for one in prose and the agent tells you to run the command, or offers a fixed cadence instead.

Fixed loops

Put an interval before the task, or end the task with an every ... clause:

Fixed loops

/loop 20m review the release pull request /loop check whether the migration completed every 2 hours /loop 1d summarize open issues

Intervals accept s, m, h, and d. The trailing form also takes spelled-out units such as minutes or hours.

Cadence normalization

Fixed loops run on cron. Cron has one-minute resolution and wants a step that divides evenly into the hour or the day, so the interval you ask for is snapped to the closest clean cadence. The confirmation tells you when that happened.

RequestedRuns as
SecondsRounded up to whole minutes, then treated like minutes.
Minutes or hoursThe nearest clean step. Minutes are 1, 2, 3, 4, 5, 6, 10, 12, 15, 20, or 30. Hours are 1, 2, 3, 4, 6, 8, or 12. Past that it becomes once a day.
24 hours or 1 dayOnce a day at midnight.
2 to 31 daysEvery N days, on cron's day-of-month field.

Ties round up. 8m becomes every 10 minutes and 45m becomes every hour. Multi-day steps follow the calendar and start over on the first of each month, so /loop 10d fires on the 1st, 11th, 21st, and 31st.

Jitter and lifetime

Fixed loops get a small deterministic delay so many sessions do not hit the API at the same instant. A recurring task can fire up to 10% of its interval late, capped at 15 minutes. The offset is derived from the task id, so it survives a resume.

Recurring tasks expire seven days after creation. An expiring loop fires one last time and is removed. If a task has to run longer than that, re-create the loop or use an external scheduler.

Self-paced loops

Skip the interval and the agent decides when to look again:

Self-paced loop

/loop watch the build and tell me when it finishes

Each iteration ends by picking a delay between one minute and one hour, with a one-line reason that shows up in the iteration result. A build that is still moving gets checked soon. A quiet one gets left alone for longer. The new delay replaces the pending wakeup rather than adding a second one, and it is not jittered.

RuleDetail
One per conversationStarting another self-paced loop replaces the pending one.
Quiet checks are countedAn iteration that changed nothing is marked quiet. The next wakeup reports the streak, which nudges the agent to back off while nothing is happening.
It stops itselfWhen the task is complete, or another check cannot help, the loop ends with a final report.
Safety check on omissionIf an iteration ends without scheduling the next check or stopping, Command Code schedules one 20-minute safety check. A second omission ends the loop.

The default task and loop.md

A bare /loop, or /loop <interval> with no task, runs a built-in maintenance task. It continues unfinished work from the conversation, then checks the current branch for review feedback, failed checks, or conflicts it can act on. If nothing is pending it makes one bounded quality pass on the work already in scope. It does not authorize unrelated work or widen permission for destructive actions.

Replace that task with a markdown file:

PathScope
.commandcode/loop.mdThe directory Command Code was started in, the same place settings.json is read from. Wins when both exist.
~/.commandcode/loop.mdFallback for projects without their own file.

The file is read again on every default-task iteration, so an edit applies to the next check without restarting the loop. Empty files are ignored. Content past 25,000 bytes is cut off. A task you type into /loop yourself never reads either file.

Example loop.md

Check the open pull requests on this branch. Reply to review comments that only need a one-line answer, push fixes for failing lint, and report anything that needs a human decision.

Stopping a loop

ActionEffect
Press EscCancels every fixed and self-paced loop in the conversation. Reminders and other schedules are left alone.
Press Esc twiceNeeded when something else is open. The first Esc closes a permission prompt, question, transcript view, banner, or overlay and leaves loops scheduled. The second Esc, at the idle prompt, cancels them.
Press Ctrl + C during a turnInterrupts the turn and cancels the conversation's loops with it.
Let it stop itselfA self-paced iteration ends the loop as soon as the task is complete.
Ask"cancel the deploy check" runs cron_delete on the loop's id.

The feed shows Loop stopped · N scheduled tasks cancelled when loops are cancelled. If you do not see that line after pressing Esc, the loops are still running. This matters when a loop iteration raised a permission prompt: Esc denies the prompt but does not stop the loop. A fire that was queued behind a busy turn is re-checked before it runs, so a cancelled loop never sneaks in one last iteration.

To see what is scheduled, ask "what scheduled tasks do I have?". cron_list returns fixed and self-paced loops with their eight-character ids. A conversation holds at most 50 scheduled tasks.

Resume and firing behavior

Loops belong to the conversation. Closing Command Code pauses them. --resume or --continue brings back loops that are still inside their seven-day lifetime. A self-paced loop that was mid-iteration when the session closed comes back as a pending 20-minute safety check. A fresh conversation never runs another conversation's loops.

The scheduler checks once a second and only submits a due iteration between turns. If the agent is busy, one due event waits for the turn to finish. Missed intervals do not pile up into a burst of catch-up runs. A scheduled /skill reference runs only when that skill is enabled and allows model invocation.

Info

/loop uses the same scheduler as one-time reminders and cron_create. Scheduled tasks and loops covers the tools underneath, one-shot reminders, and durable machine-level schedules.

Where /loop runs

/loop needs an interactive, top-level conversation. It is unavailable in these places:

SurfaceBehavior
Headless runs (-p)/loop is refused with a notice and no task is created. Use an external scheduler to run a headless prompt on a cadence.
Sub-agentsschedule_wakeup is withheld, so a sub-agent cannot start or continue a self-paced loop.
Plan modeScheduling is a write action. /loop says it cannot start and creates no task. Leave plan mode and run it again.

Kill switch

Environment variableEffect
COMMANDCODE_DISABLE_CRON=1Disables /loop and every scheduler tool. Read at launch, so loops restored into a resumed conversation do not fire while it is set.

Examples

Babysit a pull request

Fixed loop

/loop 20m check the release pull request, investigate failed checks, and push fixes for anything that is clearly this branch's fault

The task runs once now, then every 20 minutes. Resume the conversation to keep it going after a restart, press Esc to stop it, or ask Command Code to cancel it by id.

Poll a deploy until it settles

Self-paced loop

/loop check whether the production deploy finished and smoke test the site

The first checks come fast while the rollout is moving. Once the deploy is healthy and the smoke test passes, the loop stops itself and reports.

Keep a branch tidy

Default task on a cadence

/loop 1h

Every hour, Command Code continues unfinished work, tends review comments and CI on the current branch, then makes one bounded quality pass. Drop a .commandcode/loop.md in the project to change what the bare command does.

Next steps