Cursor /loop skill

Cursor /loop skill

One-liner

/loop is a Cursor built-in Agent skill (slash-invoked in Agent chat, IDE or CLI) that re-runs a prompt or another skill on a local schedule — fixed interval and/or event watchers, with a timed heartbeat as fallback when self-paced. It is not a pstack skill, not Automations, and dies with the session.

Shipped in Cursor 3.5 (changelog index: “3.5 May 20, 2026”; dedicated entry Shared Canvases and /loop Skill, 2026-05-20). Listed in the built-in skills table on Agent Skills. Executable skill body (mirrored): kevinliu.biz wiki — loop (origin: cursor-plugin, source_repo: cursor/skills-cursor, disabled-environments: [cloud]).

---

1. What it is

From the 3.5 announcement:

With /loop, Cursor can run a prompt repeatedly on a local schedule, until a certain outcome is achieved, or until you stop it. If you don’t specify a fixed interval, the agent decides when or what event should wake it.

Skills docs one-liner: “Runs a prompt or skill repeatedly at a specified interval.” (docs/skills)

Invoke via / in Agent chat (same path as other built-ins). Typical uses in the announce: “check deploy status every 5 minutes” or “work on this feature until tests pass.”

---

2. Syntax + how it wakes

Skill parse (from executable SKILL.md via wiki mirror):

/loop [interval] <prompt>

Form	Example	Behavior
Leading interval	/loop 5m check deploy	Fixed schedule
Trailing interval	/loop check deploy every 5m	Fixed schedule
No interval	/loop work until tests pass	Dynamic / self-paced
Another skill	/loop 5m /foo	Re-invokes that skill each tick
Empty prompt	/loop	Usage hint

Interval tokens: 30s, 5m, 2h, 1d (unit words converted to short units).

Fixed schedule wake

Monitored background shell loop:

while true; do
  sleep <seconds>
  echo 'AGENT_LOOP_TICK_<purpose> {"prompt":"<prompt>"}'
done

• Started with notify_on_output on a unique sentinel regex (^AGENT_LOOP_TICK_…).
• Prompt runs once immediately after arming; first sentinel arrives only after the initial sleep (no double-run at startup).
• On each tick, agent reads the latest payload JSON and runs prompt.

Dynamic (self-paced) wake

1. Run the prompt now.
2. If gated on an event (git ref, log line, file change, CI, …): arm a background watcher that emits AGENT_LOOP_WAKE_<purpose> {"prompt":…} only when the event fires (notify_on_output on ^AGENT_LOOP_WAKE_…).
3. At end of turn, arm a one-shot sleep heartbeat with the same AGENT_LOOP_WAKE_… sentinel — fallback when a watcher is armed (lean long); primary cadence when there is no watcher.
4. On wake: execute payload prompt, re-arm heartbeat (and watcher only if it exited).
5. Stop = kill watcher PID + do not arm next heartbeat.

Guidance from the skill: prefer monitored shell stdout over OS cron when the agent needs wake-on-output; unique sentinels; no duplicate loops; title shells like Loop every 5m: ….

---

3. Session lifetime / stop conditions

Local only. Loops live in the Agent chat session’s monitored background shells. They end when:

Stop	Source
User stops the loop / kills the shell	Announce + skill (“until you stop it”; skill: kill tracked PID, await shell so completion notify doesn’t re-wake)
Outcome met	Announce: “until a certain outcome is achieved”
Session ends	Quit Cursor, sleep/close laptop, kill terminal, chat/agent teardown — local loops do not outlive the session

Staff confirmation (forum #162544, @mohitjain): a background shell for a loop isn’t guaranteed to outlive the chat once the turn ends and the session goes idle. Wake-on-output across a long idle window is not guaranteed.

For work that must survive lid-close / quit, use Automations (cloud) or an external scheduler that writes a log the agent can read later — not /loop alone.

---

4. What it is NOT

Thing	Why different
Cursor Automations (/automate, cursor.com/automations, docs)	Persistent cloud agents on cron / GitHub / GitLab / Slack / webhooks / Linear / Sentry / PagerDuty, etc. Billed as cloud agent usage. Create via Agents Window, dashboard, /automate, or Marketplace templates.
Cloud Agents / Background Agents by itself	/loop is a local session skill; skill frontmatter has disabled-environments: cloud. Automations spawn cloud agents; /loop does not.
Grok Bot routines	Separate product/runtime; not this skill.
Claude Code /loop	Different product’s slash command; do not conflate.
pstack / user skills	Built-in Cursor skill (cursor-plugin / cursor/skills-cursor), not a user or pstack pack skill.
OS cron / launchd / tmux alone	Can schedule work, but cannot wake the Agent via notify_on_output unless wired back into a monitored Cursor shell.

---

5. Pairing with /goal

From Agent overview — Goals with /goal:

• /goal … gives a long-lived objective until fully complete (rolling out; try a new chat if missing).
• CLI: Ctrl+C pauses the goal.
• Docs explicitly: pair a goal with a Custom Mode (playbook) or with built-in /loop for a prompt/skill on a recurring or variable interval. No fixed interval → agent chooses when to wake. Stop the loop when you want it to end.

Pattern: /goal = durable objective; /loop = recurring check-in / poll / keep-working cadence against that objective.

---

6. Known bugs / doc gaps

Staff-confirmed bug: long-interval local loops die before first tick

Forum thread (opened 2026-06-05; still relevant as of staff update 2026-09-24):

• Fixed-interval /loop arms sleep + AGENT_LOOP_TICK_… + notify_on_output.
• With long intervals (e.g. 1h), the monitored background shell can be torn down during the idle window before the first sleep completes → sentinel never prints → loop never ticks. Short intervals often look fine because they re-wake before idle teardown.
• Follow-up (Glass / 3.12.x): idle extension-host recycle ([GlassWorkspaceLsp] disabling (idle, …)) also killed even healthy short-interval loops after the agent went idle.
• 2026-09-24 staff update (@mohitjain): latest stable stops recycling the extension host while a /loop shell is still running (mitigates the Glass idle-recycle path). Caveat: a separate teardown path can still kill long-interval loops — re-test hourly loops; report timing + whether you switched chats if it still dies.

Doc gaps

• No dedicated /loop docs page — only changelog blurb, skills-table one-liner, and /goal pairing note on Agent overview. Mechanism detail lives in the skill SKILL.md (community/wiki mirror), not a first-party reference page.
• Cloud path unclear — local skill declares disabled-environments: cloud; how (if at all) looping maps onto Cloud Agents is undocumented. Prefer Automations for cloud recurrence.
• Max interval / --max-* flags — not in the official skill source or Cursor docs. Treat third-party mentions of --max-turns / --max-runtime (e.g. MeritForge writeup) as unofficial; do not invent flags.
• Secondary writeups that claim /loop keeps running after you close the tab conflict with announce (“local”), skill design (session shells), and staff idle-lifecycle notes — ignore those claims.

---

7. Sources

Primary (fetched 2026-10-07):

1. Shared Canvases and /loop Skill · Changelog — announce (2026-05-20); version label 3.5 on changelog page/5
2. Agent Skills — built-in /loop table line
3. Cursor Agent overview — /goal + /loop pairing
4. Cloud agent Automations — contrast (cloud cron/events)
5. Forum: monitored loop shell dies before first tick — wake mechanism (AGENT_LOOP_TICK_…, notify_on_output) + staff bug status
6. kevinliu.biz wiki — loop skill source — full SKILL.md (parse, fixed/dynamic, disabled-environments: cloud)

Optional / not used as authority: X search for cursor /loop hit spend-cap (403) this run; MeritForge “Cursor 3.5’s /loop” article has useful 3.5 framing but invents --max-* and overstates session survival — cite only with caution.

Related vault: 2026-10-02 Overnight and long-running agents (Automations / overnight landscape; /loop is the local piece of that story).