English documentation · runtime 7.24.4 · SDK 2.6.7. Content is maintained with runtime development; see each guide's scope and review date.

Loop Mode & Scheduled Tasks

Status: Active Scope: current-state Last reviewed: 2026-08-27 Owner: ax-code runtime

AX Code has three composable automation primitives:

/loop — recurring prompts

/loop <interval> <prompt>   start (interval like 30s, 5m, 1h)
/loop status                show runs, busy-skips, and the prompt
/loop stop                  stop the loop

Examples:

/loop 5m check CI for new failures and fix any you find
/loop 30m drain the review queue

Rules:

• Interval bounds: 30 seconds to 24 hours. One loop per session — starting a new one replaces the old.
• A tick that fires while the session is busy is skipped and counted, never queued — loops cannot pile up turns.
• Every tick is an ordinary prompt turn: permissions, questions, autonomous caps, and completion gates all apply. With autonomous off, a tick simply parks at the first permission prompt.
• Hard ceiling of 500 runs per loop, then the loop stops itself with a notice.
• Loops live in the backend process only: they do not survive a restart. For durable schedules, use scheduled tasks below.

Pairing /goal with /loop

/goal owns the objective (“all tests green, no open review findings”); /loop provides the heartbeat that keeps checking. Creating a goal first runs a dedicated plan writer that stores a reviewable contract under .ax-code/goals/ (or the AX data directory when the project is not a git worktree). If planning fails the goal stays paused — /goal resume retries it. Git range checks that measure this goal’s diff use the plan-time HEAD ({BASELINE}), not origin/main, unless the objective names that remote. Goal completion remains verification-gated: the agent cannot mark a goal complete after edits without a passing verification run, and when a plan exists it must also supply evidence for every acceptance criterion.

/goal keep main green: fix any CI failure the loop finds
/loop 10m check CI status and act on failures

Goal assurance is opt-in

/goal <objective> starts immediately: it attaches no frozen acceptance contract, so completion is judged by the working plan the agent keeps (pending todos) plus a passing verification after its last change. /goal view (and the goal dialog’s “View goal details”) says so explicitly — “No assurance contract” — so the state is never something you have to infer.

/goal --assure <objective> runs the plan writer first, which freezes acceptance criteria, source references and executable checks; completion then also requires a current successful receipt for every required check (verify_project with its goalCheck id). Use it when the goal’s “done” must be provable rather than described.

--assure combines with the budget flags in either order (/goal --assure --budget 500000 <objective>). /goal replace <objective> keeps assurance when the goal being replaced has a valid contract, so replacing can never silently weaken a goal that was already assured.

Goal budgets and ceilings

An active goal lifts the per-run auto-continuation cap (session.max_continuations) — the run keeps going until the goal is complete, blocked, paused, or budget-limited. What bounds it instead:

• Token budget (/goal --budget N …): when exhausted, the agent gets one wrap-up turn, then the goal becomes budget_limited.
• Time budget (/goal --time-budget 30m …): a wall-clock limit in seconds, minutes (m), or hours (h), combinable with the token budget in either order. It bounds elapsed work the token budget cannot see — remote training jobs, long tool calls, provider stalls. The same wrap-up turn and budget_limited transition apply when it trips.
• Cumulative step ceiling: active-goal runs share the Super-Long backstop of max_steps × 40 total steps (20,000 by default) instead of the ordinary autonomous ceiling of max_steps × (max_continuations + 1). Override with session.max_total_steps.
• Doom-loop detection, blast-radius caps, and the tool-only-turn breaker still apply throughout.

Goal CLI (headless)

The same goal control is available outside the TUI under ax-code goal:

• ax-code goal status [--json] — show the current goal (-s/--session to pick a session; defaults to the project’s single resumable goal and errors when the choice would be ambiguous).
• ax-code goal pause / ax-code goal clear — pause or clear it.
• ax-code goal resume — resume the goal and drive it headlessly until it settles. Without --attach it bootstraps the project in-process; with --attach http://localhost:4111 it drives a running server instead. Exit codes follow the headless goal contract: 0 complete, 3 blocked, 4 budget-limited, 6 paused/non-terminal, 1 session error, 124 idle timeout (--idle-timeout-ms, default 10 minutes). Events stream to stdout as JSONL (--event-log PATH also records them), and a final Goal <status>: <objective> line goes to stderr.

As a goal run approaches the step ceiling the agent receives a one-time convergence warning telling it to verify and complete the goal or leave a clean hand-off. If the ceiling is reached anyway, the goal is paused — not failed — and can be picked up again with /goal resume (raise session.max_total_steps first if it needs more headroom).

Scheduled tasks — durable, conversational

Ask the agent directly; it uses the schedule_task, list_scheduled_tasks, and manage_scheduled_task tools:

• “Remind me at 14:30 to check the deployment.”
• “Every weekday at 9am, summarize new CI failures.”
• “List my scheduled tasks.” / “Pause the CI summary task.”

Agent-created and agent-managed schedule changes request the schedule permission. A read-only run cannot change or trigger a schedule. For unattended headless creation, use the explicit ax-code schedule command or configure an explicit schedule permission grant for the agent; broad wildcard grants do not authorize schedule changes.

The same tasks are manageable from the shell without opening the TUI:

ax-code schedule list                 # status, next run, schedule, id, title
ax-code schedule show <id>            # details plus the five most recent runs
ax-code schedule runs <id>            # run history: fired, failed, skipped and why
ax-code schedule pause|resume <id>
ax-code schedule delete <id>
ax-code schedule run <id>             # trigger now; requires a live runtime

pause/resume/delete go through the project’s managed runtime when one is running (immediate effect, live TUI updates) and otherwise write the project database directly. run needs a live backend — start one with ax-code runtime start — because a one-shot CLI process must not claim work it cannot finish. All read subcommands accept --json.

Schedules support one-time runs, daily/weekly times, and 5-field cron expressions, each with an optional IANA timezone. Tasks persist in the project database and fire while an AX Code backend for the project is running (60s scheduler sweep, atomic claiming — a task fires once even with several backends open). Schedule advancement and durable queue insertion share one database transaction, so a crash cannot advance an occurrence without leaving work to recover. One-shot commands such as ax-code run and ax-code stats do not claim due tasks. Start a persistent backend with ax-code runtime start to dispatch them.

Missed occurrences default to catchUpPolicy: "run_once": after downtime, AX Code coalesces any backlog into one run. Use "skip" when stale work should be advanced without running. A task can also set maxRunDurationMs from one second through 72 hours; a timed-out run is cancelled and recorded as failed.

For operation across process and host restarts, run the backend under a supervisor. See Long-Running Operations for systemd, launchd, and PM2 examples plus exact recovery semantics.

Long unattended runs

For multi-hour autonomous sessions, Super-Long mode adds run deadlines (up to 72h), request pacing, and compaction tuning. It auto-enables for models whose declared capabilities support long-agent work (1M-context reasoning models such as Qwen 3.7+ Max/Plus on Alibaba routes and GLM 5.x on z.ai routes) and can be forced per session, per project, or via AX_CODE_SUPER_LONG. Run engagement is logged (super-long run engaged), and provider pacing only starts after a grace window from run start (default 2 hours, super_long.pacing_grace_minutes) so the productive early phase of an agentic run keeps full tool-call throughput; the marathon tail is paced per the model’s declared rate-limit tier.