Claude Code Scheduled Execution | 4 Methods and How to Avoid the Pitfalls

Claude Code Scheduled Execution — Quick Reference for Choosing Among 4 Methods

Claude Code's scheduled execution falls into 4 categories: "run within a session," "run in the cloud," "run on your own PC," and "launch from external cron." Anthropic's official documentation includes a comparison table for the first 3 categories on the Scheduled tasks page, while external cron via Claude Code Action (GitHub) or direct CLI invocation is a widely used de facto option (Source: Run prompts on a schedule).

The 3 native methods are available on Pro / Max / Team / Enterprise plans and are not accessible on the Free plan (Source: Installation). Reader needs typically fall into 3 categories: "I want it to run even with my PC closed," "I want flexible configuration with cron expressions," and "I want to know how to use /schedule." Read the sections below based on your specific goal.

The Relationship Between /schedule and /loop

The /schedule command is implemented as an alias that internally invokes the /loop bundle skill. When you specify something like /schedule daily PR review at 9am in natural language on the CLI, it is converted to the corresponding cron expression and registered within the session. You can also directly edit the cron expression with the /schedule update subcommand, and it is fully compatible with the existing /loop API (Source: Run prompts on a schedule).

However, /schedule is session-scoped (tied to the current conversation) and does not persist across sessions like Routines or Desktop Schedule. For long-term operation, switching to another method is the right choice.

Cloud Routines — Recurring Execution Every Hour Even with Your PC Closed

Cloud Routines is a mechanism that automatically runs Claude Code sessions on Anthropic-managed cloud infrastructure. It bundles a prompt, target repository, connectors, and triggers into a single unit, and continues operating even when your PC is closed or powered off (Source: Routines). As it is in a research preview stage, the API format and limits may change in the future.

It is ideal for repetitive tasks you want to complete without human intervention — such as nightly backlog organization, PR review automation, and triage when alerts fire. Understanding the setup process and 3 types of triggers for Routines will reduce the time you spend confused during initial setup.

Eligibility and GitHub App Installation

Routines requires a Pro / Max / Team / Enterprise plan with Claude Code on the Web enabled at claude.ai/code. It is not available on the Free plan. If you use GitHub triggers, you need to install the Claude GitHub App on your repository — note that /web-setup in the CLI does not handle the app installation (Source: Routines).

Since execution happens via your linked GitHub account, any commits or PRs created by a routine are recorded as the executing user. Connected MCP (Model Context Protocol / a mechanism for external tool integration — details→) connectors such as Slack or Linear also run with your user account permissions. You can restrict access scope by selecting the target repository, environment settings, and connectors.

Schedule Trigger (Minimum 1 Hour)

Schedule triggers use either presets (Hourly / Daily / Weekdays / Weekly) or a cron expression specified directly with /schedule update. The minimum interval is 1 hour, and shorter expressions will be rejected. If you need execution every 5 or 15 minutes, use Desktop Schedule or /schedule (in-session) instead (Source: Routines).

Since jitter (up to 10% or 15 minutes of delay) is always added to cron expressions, specifying exactly 0 or 30 minutes (e.g., 0 9 * * *) results in larger variation. The official documentation notes that specifying an odd minute like 3 9 * * * leads to relatively smaller jitter (Source: Run prompts on a schedule).

API Trigger and curl Sample

Routines can be triggered instantly by POSTing to a dedicated HTTP endpoint /fire. In addition to the Authorization: Bearer header, the beta header anthropic-beta: experimental-cc-routine-2026-04-01 is required. During the research preview period, the request format may change, but the design accepts up to the latest 2 generations of beta headers (Source: Routines).

curl -X POST https://api.anthropic.com/v1/claude_code/routines/trig_xxx/fire \
  -H "Authorization: Bearer sk-ant-oat01-xxxxx" \
  -H "anthropic-beta: experimental-cc-routine-2026-04-01" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{"text": "Sentry alert SEN-4521 fired in prod."}'

Since you can pass alert content or any string in the text field, a common setup is to pipe webhooks from Sentry / Datadog / PagerDuty directly in for triage.

GitHub Trigger

This trigger fires in response to Pull Request or Release events. Filters allow you to narrow by author, title, label, base branch, and draft status, enabling workflows like "auto-review only PRs from external contributors" or "regenerate CHANGELOG on release." Using is draft = false to exclude drafts is standard practice (Source: Routines).

A single Routine can hold multiple triggers simultaneously, so you can bundle "every morning at 9am + API call after deploy + new PR" into one routine.

Desktop Schedule — Scheduled Tasks That Touch Local Files Every Morning

Desktop Schedule (local scheduled tasks) is a mechanism where Claude Code Desktop automatically launches a new session on your own machine. It covers requirements that cloud Routines cannot handle: direct access to local files, use of MCP configuration files, and a minimum interval of 1 minute (Source: Schedule recurring tasks).

It is well-suited for tasks such as auditing local repository dependencies before work every morning, aggregating local logs overnight, or updating internal data via an in-house MCP server. It pairs well with situations where you do not want or cannot put code in the cloud (confidential source code, internal LAN-only APIs).

Differences Between Routines and Desktop Tasks

Both are created from the Routines page in the desktop app, but when you select New routine, choosing Local creates a Desktop task while choosing Remote creates a cloud Routine. The two differ in execution location and prerequisites as follows (Source: Schedule recurring tasks):

• Desktop tasks: Machine must be running · Local files allowed · Reads from MCP configuration files · Permission prompts configured per task
• Cloud Routines: Machine does not need to be running · Local files not allowed (repository clone only) · Connectors configured per task · No permission prompts (autonomous execution)

If you need to access local files, your company's MCP configuration files, or proprietary toolchains, Desktop tasks are the only option.

Setup Procedure

Click New routine from the sidebar's Routines section and select Local. Fill in: Name (task identifier — also used as the filename), Description, Instructions (the prompt body — permission mode and model are also specified here), Schedule, and Folder (target folder; a trust dialog appears if not already trusted). Schedule presets are Manual / Hourly / Daily / Weekdays / Weekly; for other intervals (e.g., every 15 minutes), you can configure them by giving a natural language instruction within the session, such as "run tests every 15 minutes" (Source: Schedule recurring tasks).

Permission mode can be configured per task. If a tool permission is insufficient in Ask mode, the session stays pending in the sidebar. To avoid this, run the task immediately after creation using Run now and select "always allow" for each tool — subsequent uses of the same tool will be auto-approved.

Catch-Up Behavior (Missed Runs)

If you put your PC to sleep and miss a 9am task, when you wake or restart the machine, only the last missed run within the past 7 days will be executed as a catch-up. A daily task left for 6 days will only run once in total (Source: Schedule recurring tasks).

In situations where running a "9am review" at 11pm would be problematic, you can add a guard condition in the prompt such as "if it's past 5pm, skip today's run and just post a missed summary" to prevent accidents. The prompt body for a task is saved with YAML frontmatter in ~/.claude/scheduled-tasks/<task-name>/SKILL.md, and direct file edits take effect from the next run.

/schedule and /loop — Running Repeatedly Within a Session

The /schedule command (an alias for the /loop bundle skill) is session-scoped scheduling tied to the current conversation. Unlike Routines or Desktop tasks, it does not persist across sessions and automatically expires after 7 days — a key characteristic (Source: Run prompts on a schedule).

It is ideal for short-term polling attached to an open session, such as "check every 5 minutes whether the deploy finished" or "keep picking up comments on a PR." It is not suited for long-term monitoring.

3 Calling Patterns

/schedule (/loop) behaves in 3 different ways depending on how arguments are provided (Source: Run prompts on a schedule):

• Interval + prompt: /loop 5m check the deploy runs every 5 minutes at a fixed interval. Units are s, m, h, d; values that cannot be rounded to a cron are approximated.
• Prompt only: /loop check whether CI passed lets Claude dynamically choose the interval. It adjusts between 1 minute and 1 hour based on what it observes.
• Nothing specified: Running /loop alone launches the built-in maintenance prompt (incomplete tasks + PR care + cleanup) at a dynamic interval. This can be overridden with .claude/loop.md or ~/.claude/loop.md.

Stop by pressing Esc while waiting. A session can hold up to 50 tasks. When resuming with --resume / --continue, only tasks within their validity period (7 days) are restored; tasks are lost if you start a new session.

Combining with Auto Mode

Combining /schedule with Auto mode as the permission mode enables "running overnight without confirmation." Since Auto mode is activated without the --enable-auto-mode flag on Max + Opus 4.7 and later (currently Opus 4.8), you can attach long overnight tasks to in-session /loop and just check results the next morning (Source: Use Claude Code Desktop).

Note that Auto mode is distinct from Bypass permissions (sandbox-only, all permissions granted) — for production repositories, using Auto mode with its safety checks enabled is the correct approach.

Choosing Between GitHub Actions cron / OS crontab

In addition to the 3 native methods, Claude Code can also be called from external cron as a CLI tool. When you want to incorporate Claude Code into an existing GitHub Actions workflow or OS crontab, the question of whether to use a native method or external cron becomes the decision point.

The selection criteria come down to 3 factors: "integration with existing CI assets," "cross-repository operations," and "infrastructure management scope." Organizations that already have many GitHub Actions workflows will find more consistency in calling Claude Code Action with a cron trigger. OS crontab is effective for running on a personal home server or always-on workstation.

GitHub Actions cron + Claude Code Action

GitHub Actions' schedule trigger uses cron syntax, and you can call Claude Code Action (anthropics/claude-code-action) for recurring execution. While you can write cron syntax for every-minute intervals, GitHub's scheduler fires at a minimum of every 5 minutes (officially stated as the minimum) (Source: GitHub - Schedule events).

Compared to cloud Routines, GitHub Actions cron has the advantage of integrating with existing CI assets, Secrets management, and Artifacts. However, the execution environment is ephemeral per runner, so Routines is better suited when you need to retain long-term context. Since each job consumes API token quota, absorbing high-frequency runs within a Routines subscription is more cost-effective.

OS crontab + Claude Code CLI

You can also register Claude Code CLI directly in Linux/macOS crontab — for example, using crontab -e to write 0 9 * * * /usr/local/bin/claude --print "Summarize this morning's emails". The minimum interval follows OS cron specifications (1 minute).

OS cron is suitable for always-on workstations or home servers, but compared to Desktop Schedule, it offers less granular control over permission modes (Auto / Ask) and does not support SKILL.md-style template management. For serious use, migrating to Desktop Schedule will be more maintainable.

Pitfalls of Scheduled Execution — Free Plan Restriction, 1-Hour Minimum, 7-Day Expiry

Here we summarize the typical constraints you'll run into if you start without reading the official documentation, along with workarounds. Always verify primary sources together with hands-on testing. This section covers the 6 items that come up most frequently during initial setup.

We go through them in order: Free plan misunderstanding, Routines 1-hour minimum, /schedule 7-day expiry, Desktop task PC sleep issue, cron expression jitter, and the required beta header for API triggers — each paired with an explanation of why it works that way and how to avoid the issue.

Free Plan Cannot Use Claude Code at All

Claude Code requires Pro ($20/month) or higher; /schedule, Routines, and Desktop Schedule are all inaccessible on the Free plan. For those who want to "run Claude on a schedule for free," a Pro subscription is a prerequisite — that's the first thing to know (Source: Installation). For pricing details, see Complete Guide to Claude Pricing.

Routines Minimum Interval Is 1 Hour — Cannot Run Every 5 Minutes

Routines has a minimum execution interval of 1 hour, and short-interval cron expressions like */5 * * * * will be rejected. If you need execution every 5 or 15 minutes, use local Desktop tasks (minimum 1 minute) or /schedule (minimum 1 minute) instead (Source: Routines).

Routines also has a separate per-account daily routine execution cap, which operates independently of normal subscription usage. One-off runs do not count against this daily cap.

/schedule Expires After 7 Days — Do Not Use for Long-Term Monitoring

A /schedule task that reaches 7 days without the session being resumed will fire once more and then be automatically deleted. For use cases like monitoring for a month after a release, it will expire — so making it persistent with Routines or Desktop tasks is the right approach (Source: Run prompts on a schedule).

For short-term polling, /schedule is sufficient, but keeping "long-term operation = different method" as a decision principle from the start helps you avoid the hassle of restructuring your setup later.

Desktop Schedule Misses Tasks During PC Sleep — Prevent with Keep Awake

Closing a laptop lid puts it to sleep, and Desktop tasks scheduled during that time will only run once as catch-up. Enabling Settings → Desktop app → General → Keep computer awake prevents idle sleep. Note that closing the lid still triggers sleep despite this setting, so if you need tasks to run every night, the PC must remain connected to power with the lid open (Source: Schedule recurring tasks).

If you need tasks to run while you're away, choosing cloud Routines from the start reduces operational burden.

Cron Expressions Include Jitter (Up to 10% / 15 Minutes)

Cron expressions with 0 minutes like 0 9 * * * always have jitter added (up to 10% or 15 minutes of delay). For cases where you need tasks to run as close to exactly 9:00 as possible, the official documentation notes that specifying an odd minute like 3 9 * * * results in relatively smaller jitter (Source: Run prompts on a schedule).

When using 0 * * * * frequently for hourly execution, design your jobs so that many tasks from one account don't all fire at the same time — this avoids rate limiting caused by retry storms.

Routines API Trigger Requires Beta Header

The /fire endpoint requires the anthropic-beta: experimental-cc-routine-2026-04-01 header, and requests without it will be rejected. During the research preview period, the request/response format may change, but the design accepts up to the latest 2 generations of beta headers (Source: Routines).

For production use, explicitly including this header in your secrets management helps prevent accidents during rotation. "Forgetting the beta header and getting a 400 error" is something almost everyone encounters during their first week of setup.

Sources (Primary Information)

If you want to verify the official documentation in its latest version, refer to the following. Features in the research preview stage (Routines / Auto mode) may be subject to specification changes in the future.

• Run prompts on a schedule — Primary source for /schedule / /loop / cron expression jitter rules
• Automate work with routines — Routines triggers, creation, and API reference
• Schedule recurring tasks in Claude Code Desktop — Desktop Schedule comparison table and catch-up behavior
• Use Claude Code Desktop — Auto mode and Bypass permissions mode explanations
• Claude Code Changelog — Auto mode specification change history from v2.1.111 (2026-04-16) onwards
• GitHub - Events that trigger workflows: schedule — GitHub Actions cron specifications

Related Articles

Reviewing how Claude Code works and its pricing before incorporating scheduled execution will help you avoid mistakes.

• Claude Code Automation Guide — Routines, Headless, 4 Methods — Detailed explanations of Routines trigger types, Headless mode, and CI integration
• Claude Code April Major Updates Summary — Breaking news on Auto mode, Routines, and xhigh
• Complete Guide to Claude Code — Installation and basic operations introduction
• Complete Guide to Claude Pricing — Pricing and plan-specific features for Pro / Max / Team