Why /loop Matters in Claude Code

The problem /loop was built to solve

Anyone who lives in Claude Code eventually notices the same friction: they keep typing the same prompt over and over. "Did the deploy finish?" "Is CI green yet?" "Any new review comments?" The work isn't hard; it's the waiting and re-asking that drains attention. You sit there refreshing a terminal like an anxious intern, breaking focus every few minutes to ask Claude a question you've already asked five times.

/loop exists to remove that cognitive overhead. Instead of manually re-running a check during an active session, you describe the task once and let Claude re-execute it on a cadence while you keep working. It is, in the simplest terms, a way to hand the polling work to the machine, which is exactly the kind of work a machine should be doing.

The deeper reason it matters is that it changes the shape of what a Claude Code session can be. A normal run executes once and exits. A loop stays alive between cycles: Claude wakes at each interval, runs the task, reports back, and goes idle again. That turns a single conversation into a lightweight monitoring agent that runs alongside you.

What /loop actually is

/loop is a session-scoped scheduling primitive. It runs a prompt, or any slash command, repeatedly on an interval inside your current Claude Code session. It requires Claude Code v2.1.72 or later.

It is not a fourth automation system competing with hooks, skills, and subagents. It's a convenience layer that adds time-based repetition to the session you're already in. And critically, it is not a raw cron job. You never write a cron expression. You describe the task and the cadence in plain English, and Claude converts that into the underlying schedule, confirms the cadence, and hands back a job ID.

The distinction from cron matters. A naive alternative is wrapping claude -p "your prompt" in a shell script and dropping it into your system crontab. That works, but it's fragile: you're now managing authentication state, output logging, error handling, and context by hand. /loop runs inside Claude Code's own interface, so it inherits your session's context, your MCP servers, and your permission settings automatically. Each iteration also runs in the same conversation, so Claude can see what it observed in previous cycles. That enables trend detection, "the error count has risen across the last three checks," which a stateless cron script can't do on its own.

The three ways to run it

What you provide determines how the loop behaves. This is the core mental model:

1. Interval and prompt: runs on a fixed schedule.

/loop 5m check if the deployment finished and tell me what happened

Claude converts 5m to a cron expression and fires the prompt every five minutes. The interval can lead as a bare token (30m) or trail as a clause (every 2 hours). Supported units are s, m, h, and d. Seconds round up to the nearest minute (cron has one-minute granularity), and intervals that don't map cleanly (7m, 90m) get rounded to the nearest valid step, with Claude telling you what it picked.

2. Prompt only: Claude chooses the interval each cycle.

/loop check whether CI passed and address any review comments

With no interval, Claude picks a delay between one minute and one hour after each iteration, based on what it just saw: short waits while a build is finishing or a PR is active, longer waits when things go quiet. It prints the chosen delay and its reasoning at the end of each run. In this self-paced mode, Claude can also end the loop on its own once the task is provably complete: it simply stops scheduling the next wakeup. (For dynamic schedules, Claude may also reach for the Monitor tool, which streams a background script's output line by line instead of polling, often more efficiently.)

3. Interval only, or nothing: runs the built-in maintenance prompt.

/loop

A bare /loop runs a built-in maintenance routine at a dynamically chosen interval. On each pass it works through, in order: continuing unfinished work from the conversation; tending the current branch's PR (review comments, failed CI, merge conflicts); and running cleanup passes like bug hunts or simplification when nothing else is pending. Importantly, it stays in scope: it won't start new initiatives, and irreversible actions like pushing or deleting only proceed when they continue something the transcript already authorized.

You can also pass a saved command as the prompt, /loop 20m /review-pr 1234, to re-run a packaged skill or workflow on each cycle. This is where it compounds: a review workflow you've already built now runs on a schedule without any extra setup.

Customizing the default with loop.md

You can replace the built-in maintenance prompt with your own by creating a loop.md file. Claude checks two locations and uses the first it finds:

• .claude/loop.md: project-level, takes precedence
• ~/.claude/loop.md: user-level, applies anywhere without a project-level file

The file is plain Markdown with no required structure: write it exactly as you'd type a /loop prompt. A practical example for keeping a release branch healthy:

Check the `release/next` PR. If CI is red, pull the failing job log,
diagnose, and push a minimal fix. If new review comments have arrived,
address each one and resolve the thread. If everything is green and
quiet, say so in one line.

Edits take effect on the next iteration, so you can refine the instructions while a loop is already running. Keep it concise: content beyond 25,000 bytes is truncated.

One-time reminders

You don't always need a repeating loop. For a single-fire task, just describe it in natural language, no /loop prefix needed:

remind me at 3pm to push the release branch

in 45 minutes, check whether the integration tests passed

Claude pins the fire time to a specific minute and hour and confirms when it'll run. The task deletes itself after it fires.

Where it earns its keep

The strongest use cases all share one shape: "keep checking until X."

• Deployment watching. Poll a staging endpoint and surface the HTTP status the moment it goes live, instead of refreshing manually.
• CI babysitting. Combined with the gh CLI, Claude can monitor CI status, read failure logs, identify the problem, push a targeted fix, and re-run the workflow, closing the loop on a red build without you in the chair.
• PR polling. Re-run a packaged review command against an open PR on a cadence.
• Log and error scanning. Summarize new errors on an interval and flag regressions across cycles.
• MCP-driven summaries. Because a loop inherits every MCP server in your session, a daily loop can read Slack as a first-class data source and write to Linear as a first-class output, not scraping pages or parsing exports, but operating on the real systems.

The unifying principle, borrowed from good autonomous-agent discipline, is to leave the environment in a known state after every cycle (for example, committing after each CI fix) so each iteration starts clean.

The limitations, and why they're by design

/loop is deliberately session-scoped, and understanding that boundary is what separates good use from frustration:

• Tasks fire only while Claude Code is running and idle. Close the terminal or let the session exit, and they stop. A scheduled prompt fires between your turns, never mid-response: if Claude is busy when a task comes due, it waits until the current turn ends.
• No catch-up for missed fires. If a scheduled time passes while Claude is on a long request, the task fires once when Claude goes idle, not once per missed interval.
• Starting a fresh conversation clears all loops. Resuming with claude --resume or --continue restores tasks that haven't expired (recurring tasks within seven days of creation, one-shot tasks whose time hasn't passed).
• Seven-day expiry. Recurring tasks fire one final time at the seven-day mark, then delete themselves, a guardrail against forgotten loops running forever.
• Loops burn tokens on every iteration, and context grows across cycles. Set a sensible interval and a stop condition; don't loop one-off work.

A session can hold up to 50 scheduled tasks at once, each with an 8-character ID. You manage them conversationally ("what scheduled tasks do I have?", "cancel the deploy check job") or by pressing Esc to stop a waiting /loop. The scheduler can be disabled entirely with CLAUDE_CODE_DISABLE_CRON=1.

When /loop is the wrong tool

The session-scoped design is a feature, not a shortcoming, but it means /loop is the wrong choice for durable, team-critical, or unattended automation. Anthropic offers three other mechanisms for that layer:

• Routines run on Anthropic-managed cloud infrastructure, on a schedule, via API call, or on GitHub events: no machine required, no open session.
• Desktop scheduled tasks run locally with access to your files and tools, persisting across restarts without an open session.
• GitHub Actions use a schedule trigger in CI for repository-level automation.

There's also a related-but-different in-session tool worth knowing: /goal keeps the session working turn after turn until a condition is met, rather than firing on a timer. And Channels let external events (CI alerts, production errors, PR comments, webhooks) push into a session, so you can react to events instead of polling for them.

The clean rule of thumb: think of /loop as your in-session copilot, not your overnight cron daemon. If you're already in Claude Code and need something to run while you work, reach for /loop. If the automation needs to survive a closed laptop or serve a team, reach for one of the durable options instead.

The bottom line

/loop matters less because it's a flashy feature and more because it closes a specific, constant gap in real development work: the gap between "I need to keep an eye on this" and "I want to keep making progress." It takes about ten seconds to set up, it interprets results rather than just fetching them, and it accumulates context across cycles so it can spot trends. Used within its design (session-scoped, time-bounded, token-aware) it quietly removes a category of busywork that engineers have tolerated for years.