Claude Code /loop Command: Complete Guide to Automated Recurring Tasks

Last updated: March 22, 2026 | Reading time: 22 minutes | Author: David Henderson

TL;DR

The /loop command is a March 2026 addition to Claude Code that runs any task on a recurring interval within your current session. It turns Claude Code from a one-shot assistant into a persistent monitoring and automation layer — checking build status, watching test results, polling APIs, auditing dependencies, and more, all without leaving the terminal.

Key things to know:

• Session-scoped — loops run only while your Claude Code session is active. Close the session, and all loops stop cleanly.
• Flexible intervals — supports seconds (30s), minutes (5m), and hours (1h) with a minimum interval of 10 seconds.
• Multiple concurrent loops — run several /loop tasks simultaneously, each with its own interval and task definition.
• Pairs powerfully with hooks, worktrees, and agent teams — the real value emerges when /loop is combined with other Claude Code primitives.

3 loops to set up right now:

1. /loop 60s "run npm test and report any failures" — continuous test watching during development
2. /loop 5m "check if any open PRs have new review comments" — PR review polling so nothing slips through
3. /loop 30m "run npm audit and flag any new critical vulnerabilities" — passive dependency security monitoring

Read on for 10 production-ready recipes, advanced patterns, and a full comparison against desktop schedulers and GitHub Actions.

Table of Contents

1. What Is the /loop Command?
2. Key Features
3. 10 Practical /loop Recipes
4. /loop vs Desktop Scheduled Tasks vs GitHub Actions
5. Advanced Patterns
6. Troubleshooting
7. Pros and Cons
8. Frequently Asked Questions
9. Related Articles

What Is the /loop Command?

The /loop command was introduced in Claude Code's March 2026 update as a built-in slash command for scheduling recurring tasks within an active session. It tells Claude to execute a specific task repeatedly at a defined interval — and to keep doing it until the session ends, the user cancels the loop, or a stop condition is met.

Here is the basic syntax:

/loop <interval> "<task description>"

For example:

/loop 60s "run the test suite and summarize any failures"
/loop 5m "check the deployment status of the staging environment"
/loop 1h "audit the project for unused dependencies"

The interval accepts three units: s for seconds, m for minutes, and h for hours. The minimum interval is 10 seconds — anything lower is rejected to prevent runaway resource consumption. The task description is a natural language instruction, not a raw shell command. Claude interprets the task, decides which tools to use (Bash, Read, Grep, etc.), executes it, and reports the result before waiting for the next cycle.

This distinction matters. Unlike watch or cron, the /loop command does not blindly re-run a static command. Each iteration is an intelligent execution where Claude can adapt its approach based on what it finds. If a test fails, Claude can investigate the failure. If a deployment is stuck, Claude can check logs. The task description is a goal, not a script.

The /loop command is session-scoped by design. Loops do not persist across sessions, do not survive terminal closures, and do not run in the background after Claude Code exits. This is intentional — /loop is meant for active development workflows, not permanent infrastructure monitoring. For persistent scheduled tasks, developers should use hooks, GitHub Actions, or system-level schedulers like cron.

When a loop is running, Claude Code continues to accept normal input. Developers can chat, run other commands, and work on tasks while loops execute in the background. Loop output appears in the conversation when each iteration completes, tagged with the loop identifier and timestamp so it is easy to distinguish from regular responses.

Key Features

Interval Syntax

The /loop command supports three time units with straightforward syntax:

The parser is strict about format. 30s works. 30 seconds does not. 0.5m does not work either — use 30s instead. For intervals longer than 8 hours, the recommendation is to use a system-level scheduler instead, since sessions that long are unusual.

Choosing the right interval is a balance between responsiveness and resource usage. A 10-second loop on a full test suite will hammer the CPU. A 30-minute loop on deployment status might miss a window. The general rule: match the interval to how quickly the monitored thing changes and how urgently you need to know about it.

Session Persistence

Loops are bound to the current Claude Code session. They start when /loop is invoked and stop when any of these conditions are met:

• The user runs /loop stop or /loop stop to cancel a specific loop
• The user runs /loop stop all to cancel every active loop
• The Claude Code session ends (terminal close, Ctrl+C, /exit)
• A stop condition defined in the task description is satisfied
• The loop encounters a fatal error after exhausting its retry budget

This session-scoping is a feature, not a limitation. It means loops cannot become orphaned processes consuming resources after a developer walks away. Every loop has a clear lifecycle tied to the session that created it.

Between iterations, loops are dormant — they consume no CPU or API credits. The timer runs locally, and Claude is only invoked when the interval elapses and the next iteration begins.

Task Monitoring

Every active loop gets a unique identifier (e.g., loop-1, loop-2). Developers can inspect the state of all loops at any time:

/loop status

This returns a summary table showing each loop's ID, interval, task description, last run time, last result status, total iterations completed, and next scheduled run. It is the control panel for understanding what is running and when.

Individual loop output is also tagged in the conversation. When loop-1 completes an iteration, the output appears with a [loop-1 | 14:32:05] prefix, making it easy to scan the conversation and find loop-specific results without confusion.

For longer-running sessions with many iterations, the /loop history command shows the last N results for a specific loop, which is useful for spotting trends — like a test that started failing 20 minutes ago or an API response time that has been climbing.

Error Handling

Loops are designed to be resilient. A single iteration failure does not kill the loop. Instead, Claude Code applies a graduated retry strategy:

1. First failure — log the error, continue to the next scheduled iteration
2. Three consecutive failures — increase the interval by 2x (backoff) and warn the user
3. Five consecutive failures — pause the loop and notify the user, requiring manual /loop resume to continue

This prevents a broken command from consuming unlimited API credits while still being tolerant of transient failures like network timeouts, temporary API outages, or flaky tests.

When an iteration produces an error, Claude does not just report "error." It analyzes the failure, provides context on what went wrong, and suggests whether the issue is transient (retry will likely fix it) or structural (the task definition or environment needs to change).

Chaining with Other Commands

The /loop command integrates naturally with other Claude Code slash commands. The task description can reference any tool or capability Claude has access to:

/loop 5m "use the GitHub MCP to check if any of my open PRs have new comments"
/loop 10m "read the file at /var/log/app.log and summarize any errors since the last check"
/loop 1h "run /review on the src/api/ directory and flag any new code quality issues"

This chaining is implicit — developers do not need special syntax. Because the task description is natural language interpreted by Claude, it can leverage MCP servers, skills, file operations, bash commands, and any other capability in the session. The loop is an orchestration layer, and the task is whatever Claude can do.

Log Output

Every loop iteration generates structured output that includes:

• Timestamp — when the iteration started and completed
• Duration — how long the iteration took to execute
• Status — success, warning, error, or skipped
• Summary — Claude's natural language summary of results
• Raw output — the actual command output or tool results, collapsible for clean reading

Log output is visible in the conversation in real time. For sessions with high-frequency loops, Claude Code automatically collapses routine "all clear" iterations into a single line (e.g., [loop-1 | 14:32:05] Tests passing (42/42) — no changes) and expands only iterations where something changed or failed. This keeps the conversation readable without hiding important information.

Developers can also export loop logs with /loop export to get a markdown file of all iterations, which is useful for post-session review or sharing with teammates.

Multiple Loops

Claude Code supports running several loops concurrently within a single session. Each loop operates independently with its own interval, task, and error state:

/loop 30s "watch for file changes in src/ and report modifications"
/loop 5m "check the CI pipeline status on GitHub"
/loop 30m "run a security audit on dependencies"

There is no hard limit on the number of concurrent loops, but practical limits apply. Each loop iteration consumes API credits and processing time. Running 10 loops with 10-second intervals would produce 60 iterations per minute, which is both expensive and noisy. The recommended maximum for comfortable development flow is 3-5 concurrent loops with intervals of 30 seconds or longer.

Loops are identified by sequential IDs (loop-1, loop-2, etc.) assigned in the order they were created. The /loop status command shows all active loops, and /loop stop targets a specific one.

Graceful Shutdown

When a session ends — whether by /exit, Ctrl+C, terminal close, or network disconnection — all active loops shut down cleanly. This means:

• Any currently executing iteration is allowed to complete (with a 30-second timeout)
• No partial writes or interrupted operations are left behind
• Loop state is logged so the developer can review what happened in the last iteration
• No orphaned background processes remain after the session ends

If a developer wants to stop all loops but keep the session alive, /loop stop all does exactly that. Individual loops can be stopped with /loop stop and restarted with a new /loop command — there is no "pause and resume at the same interval" shortcut for individual loops, though /loop resume restarts a loop that was auto-paused due to consecutive errors.

10 Practical /loop Recipes

These are production-ready recipes that solve real development workflow problems. Each includes the exact command, what it monitors, and when to use it.

1. Deployment Monitoring

/loop 30s "check the deployment status of our Vercel/Netlify project and notify me when it completes or fails"

When to use it: After pushing a commit or triggering a deploy. Instead of switching to the Vercel dashboard and refreshing, this loop watches the deployment and reports the moment it completes. Especially useful for longer builds (Next.js, large monorepos) where deploy times are measured in minutes.

What Claude does each iteration: Checks the deployment API (via MCP or CLI), compares the status to the previous iteration, and only reports when the status changes. Routine "still building" iterations are collapsed to a single line.

2. Test Watching

/loop 60s "run npm test and report only if any tests fail or if the failure count changes from the last run"

When to use it: During active development when making changes across multiple files. This is a smarter alternative to jest --watch because Claude can explain why tests fail, not just which tests fail. Pair it with active coding in the same session — write code, and the loop catches breakage within a minute.

Pro tip: Set the interval to match your save frequency. If you save every 30 seconds, a 60-second loop ensures you catch failures quickly without doubling up on test runs.

3. Log Tailing

/loop 30s "read the last 50 lines of /var/log/app/error.log and summarize any new errors since the last check"

When to use it: When debugging a production or staging issue in real time. Instead of running tail -f in a separate terminal and parsing logs visually, this loop reads, filters, and summarizes log entries. Claude highlights patterns — like the same error repeating, error rates increasing, or a new error type appearing for the first time.

What makes this better than tail -f: Claude contextualizes errors. It can cross-reference a stack trace against the codebase, identify the likely source file, and suggest fixes — all within the loop iteration.

4. PR Review Polling

/loop 5m "use the GitHub MCP to check all my open PRs for new review comments, approvals, or requested changes since the last check"

When to use it: When waiting for code reviews during a workday. Instead of switching to GitHub every few minutes, this loop brings review activity into the Claude Code session. When a reviewer leaves a comment, Claude summarizes it and can even start addressing the feedback immediately if instructed.

Pair it with: A skill that auto-responds to common review patterns (e.g., "please add tests" triggers a test generation workflow).

5. Build Status Checking

/loop 2m "check the GitHub Actions CI status for the current branch and report any failures with a summary of the failing step"

When to use it: After pushing a branch that triggers CI. This loop tracks the pipeline and reports status changes — from "queued" to "running" to "passed" or "failed." When a step fails, Claude reads the CI logs and summarizes the issue, saving the developer from navigating GitHub's Actions UI to find the relevant failure.

Bonus: If Claude identifies the failing step as something it can fix (a lint error, a type error, a missing import), it can propose the fix right there in the session.

6. Dependency Audit

/loop 30m "run npm audit and compare results to the last run. Flag any new vulnerabilities, especially critical or high severity"

When to use it: During extended development sessions where dependencies might be added or updated. This is a passive security net — it runs in the background and only interrupts the developer when something changes. A 30-minute interval is sufficient since vulnerability databases update infrequently.

What Claude reports: New vulnerabilities (not seen in the last run), severity changes, and whether the vulnerability affects a direct dependency or a transitive one. For critical findings, Claude can suggest remediation steps.

7. Database Health

/loop 5m "connect to the database and check connection pool usage, active queries over 30 seconds, and table sizes for any abnormal growth"

When to use it: During load testing, after deploying database migrations, or when investigating performance issues. This loop provides a continuous health dashboard inside the Claude Code session. It catches connection pool exhaustion, runaway queries, and unexpected table growth before they become outages.

Requirements: Needs a database MCP server configured (e.g., Postgres MCP, Supabase MCP) or database CLI access via Bash.

8. API Uptime

/loop 60s "send a health check request to https://api.example.com/health and report the response time and status code. Alert me if response time exceeds 2 seconds or status is not 200"

When to use it: After deploying API changes, during incident response, or when monitoring a service during a launch. This loop is a lightweight uptime monitor inside the development session. It is not a replacement for Datadog or PagerDuty, but it is instant to set up and runs exactly as long as needed.

What Claude tracks: Response time trends (getting slower? getting faster?), status code changes, and response body anomalies. Claude can compare the current response to the expected healthy response and flag deviations.

9. Git Branch Cleanup

/loop 1h "list all local git branches that have been merged into main and are older than 7 days. Show me the list but do not delete anything without my confirmation"

When to use it: During long development sessions in repositories with many branches. This loop surfaces stale branches periodically as a reminder to clean up. It is deliberately non-destructive — it shows the list but waits for explicit developer confirmation before deleting anything.

Why hourly: Branch cleanup is low-urgency maintenance. An hourly reminder keeps the workspace tidy without being annoying. In practice, most developers act on this once per session.

10. Documentation Freshness

/loop 1h "compare the API route signatures in src/api/ against the documentation in docs/api/ and flag any mismatches where the code has changed but the docs have not been updated"

When to use it: In projects where API documentation is maintained separately from code (not auto-generated). This loop catches documentation drift — when someone changes an API endpoint but forgets to update the docs. An hourly interval is appropriate because documentation drift is a slow-moving problem.

What Claude checks: Function signatures, parameter names and types, return types, route paths, and HTTP methods. It compares the code (source of truth) against the documentation and reports discrepancies with specific file paths and line numbers.

/loop vs Desktop Scheduled Tasks vs GitHub Actions

The /loop command is not a replacement for all scheduling tools. It fills a specific niche — interactive, session-scoped, developer-centric recurring tasks. Here is how it compares to the two most common alternatives.

When to Use Each

Use /loop when:

• The task is relevant only during active development
• You need intelligent interpretation of results, not just raw output
• The task is temporary (monitoring a deploy, watching for a specific condition)
• You want zero setup overhead — just type and go
• You need sub-minute intervals for responsive monitoring

Use desktop scheduled tasks when:

• The task must run regardless of whether anyone is at the computer
• The task is a simple, static command (backup, log rotation, cleanup)
• You need true persistence across sessions and reboots
• Cost is a concern (local execution is free)

Use GitHub Actions when:

• The task is tied to repository events (push, PR, release)
• The task needs to run in a clean, reproducible environment
• Multiple team members need visibility into the task's results
• The task is part of your CI/CD pipeline
• You need the task to run even if no developer is online

In practice, these tools complement each other. A developer might use /loop during active development, GitHub Actions for CI/CD, and cron for local machine maintenance — all in the same project.

Advanced Patterns

Loop + Hooks

The most powerful /loop pattern combines it with Claude Code hooks. Hooks fire on specific events (before a tool runs, after a file is edited, when a session starts). Loops run on a time interval. Together, they create event-driven + time-driven automation.

Example: Auto-fix lint errors on a schedule

Set up a hook that logs every lint warning Claude encounters during file edits. Then run a loop that processes the lint log:

/loop 10m "read .claude/lint-warnings.log, identify recurring patterns, and fix the top 3 most common lint issues across the codebase"

The hook captures the problems in real time. The loop addresses them in batches. This separation prevents constant interruptions (fixing every lint warning immediately) while still keeping the codebase clean.

Example: Compliance audit loop with hook enforcement

Run a loop that periodically scans for compliance issues (hardcoded secrets, missing license headers, unsafe API patterns). When the loop finds a violation, it writes to a .claude/compliance-violations.json file. A PreToolUse hook reads this file before every Write or Edit operation and blocks changes that would introduce the same violations Claude just flagged.

The loop detects. The hook prevents. Together, they create a feedback cycle that continuously improves code quality.

Loop + Agent Teams

In multi-agent setups where Claude Code coordinates specialized sub-agents, /loop acts as a supervisory mechanism. The main session runs loops that monitor the work of sub-agents:

/loop 2m "check the status of all running sub-agents and report any that are stuck, have errored, or have completed their tasks"

This turns the main session into a control plane — dispatching work to sub-agents and using loops to track their progress. When a sub-agent completes a task, the loop detects it and can trigger the next step in the workflow.

Example: Parallel refactoring with monitoring

Dispatch three sub-agents to refactor different modules. Run a loop in the main session that:

1. Checks each sub-agent's progress
2. Runs the test suite after each sub-agent completes
3. Reports integration issues where one agent's changes break another module
4. Coordinates merge order to minimize conflicts

The loop provides the orchestration layer that makes parallel agent work practical rather than chaotic.

Loop + Worktrees

Git worktrees allow multiple working directories from the same repository. Combined with /loop, developers can monitor work happening across branches simultaneously:

/loop 5m "check the test results in the worktree at ../feature-auth and compare them against the main branch test results"

This is particularly useful when:

• Running a long-lived feature branch alongside main and wanting to ensure they do not diverge in test coverage
• Monitoring a hotfix branch while continuing development on a feature branch
• Comparing performance benchmarks between two implementations in parallel worktrees

The loop can access any worktree directory, run commands in that context, and report back to the main session. Combined with Claude's ability to understand code context, the loop can do more than just "run tests in both" — it can identify which specific changes in the feature branch caused test divergence and suggest how to reconcile them.

Example: Continuous integration across worktrees

/loop 3m "for each active git worktree, run the test suite, check for type errors, and verify that all worktrees are compatible with the shared dependency lock file"

This creates a local CI-like experience without pushing to a remote or waiting for GitHub Actions. The loop catches inter-branch incompatibilities in near real time during active development.

Troubleshooting

Loop Starts But Never Produces Output

Symptom: The /loop command is accepted, /loop status shows it as active, but no iteration output appears.

Cause: The interval has not elapsed yet. If the loop is set to 30m, the first iteration does not run until 30 minutes after creation.

Fix: By default, /loop runs the first iteration immediately and then waits for the interval before subsequent runs. If the first iteration is not appearing, the task itself may be hanging — check /loop status for the "currently executing" indicator. If the iteration is taking longer than expected, the task might involve a long-running command (like a full test suite). Wait for it to complete, or cancel and restart with a simpler task to verify the loop is working.

Loop Consumes Too Many API Credits

Symptom: Claude Code usage spikes significantly after starting loops.

Cause: Short intervals combined with complex tasks. A /loop 10s "analyze the entire codebase for..." command runs a substantial task 6 times per minute, each consuming API credits.

Fix: Increase the interval to match the actual cadence of change. If tests only change when files are saved, a 60-second loop is sufficient. If deployments take 5 minutes, checking every 30 seconds wastes 9 out of 10 iterations. Also, make task descriptions specific — "check if the build passed" is cheaper than "analyze the build logs, find the root cause, and suggest fixes" because the latter involves more tool calls per iteration.

Multiple Loops Interfere with Each Other

Symptom: Loop output is interleaved and confusing, or two loops seem to conflict (both trying to modify the same file).

Cause: Concurrent loops with overlapping scope. Two loops that both read and write to the same files can create race conditions.

Fix: Design loops with non-overlapping responsibilities. One loop monitors tests, another monitors deployments — they read different things and do not write. If two loops must operate on the same files, stagger their intervals (e.g., one at 60s, another at 90s) to reduce collision frequency, or combine them into a single loop with a broader task description.

If the output interleaving is the only issue (no functional conflict), use /loop status to identify each loop's output by its ID prefix. The [loop-1] and [loop-2] tags make it possible to filter visually.

Loop Stops Unexpectedly After Errors

Symptom: A loop that was running fine suddenly pauses and requires /loop resume to restart.

Cause: Five consecutive iteration failures triggered the automatic pause mechanism. This is the intended error-handling behavior — it protects against runaway loops consuming credits on a persistently broken task.

Fix: Before resuming, investigate why five iterations failed. Run the task manually (without /loop) to see the full error output. Common causes include: network connectivity changes (VPN disconnected), file paths that changed (branch switch), external service outages (GitHub API rate limits), or environment changes (database went offline). Fix the underlying issue, then /loop resume .

Loop Interval Drifts Over Time

Symptom: A loop set to 60 seconds gradually shifts — iterations happen at 62 seconds, then 65 seconds, then 70 seconds.

Cause: Each iteration has a non-zero execution time. If an iteration takes 5 seconds to complete, and the timer starts after completion, the effective interval is 65 seconds, not 60. Over many iterations, this drift compounds.

Fix: This is expected behavior, not a bug. The interval is the gap between iterations, not the period from start to start. For most monitoring use cases, a few seconds of drift is irrelevant. If precise timing matters, reduce the interval slightly to compensate for average execution time — set 55s if iterations typically take 5 seconds and you want ~60-second periodicity.

Pros and Cons

Pros

• Zero setup friction — one command, no config files, no YAML, no cron expressions. Type /loop and it is running.
• Intelligent execution — unlike static schedulers, Claude interprets results, adapts its approach, and provides actionable context.
• Session-scoped safety — loops cannot become orphaned processes. They die when the session dies.
• Flexible intervals — from 10 seconds to 8 hours covers virtually every development monitoring use case.
• Multiple concurrent loops — monitor several things simultaneously from a single session.
• Smart error handling — graduated backoff prevents runaway credit consumption without killing loops on transient failures.
• Composable — pairs naturally with hooks, skills, MCP servers, and other Claude Code primitives.
• Conversational output — results appear in the chat, tagged and timestamped, making it easy to review and act on findings.

Cons

• Not persistent — loops die with the session. Not suitable for always-on monitoring or production alerting.
• API credit cost — every iteration consumes credits. High-frequency loops on complex tasks can get expensive quickly.
• No cross-session history — loop results from a previous session are gone unless manually exported.
• Interval drift — execution time adds to the interval, causing gradual timing drift over long sessions.
• No conditional scheduling — cannot natively say "only run between 9am and 5pm" or "only on weekdays." The loop runs at its interval until stopped.
• Resource contention — many concurrent loops or short intervals can slow down the main session's responsiveness for interactive work.
• Requires active session — the developer must keep Claude Code open. This is a poor fit for tasks that need to run overnight or over weekends.

Frequently Asked Questions

Related Articles

• Claude Code Hooks: Complete Guide with 15 Ready-to-Use Examples — deep dive into event-driven automation, the natural complement to time-driven /loop tasks
• Claude Skills vs MCP Servers vs Plugins: What's the Difference? — understand the ecosystem of extensions that /loop can orchestrate
• Browse All Skills — find skills that pair well with /loop for automated workflows
• Browse All MCP Servers — discover MCP servers that give /loop access to external services and APIs

Back to Blog