How to Use Scheduled Tasks in Claude Code for Automation (2026)

Claude Code supports scheduled and recurring tasks through the /schedule slash command and the Agent SDK's CronCreate tool, letting you run autonomous AI workflows on a timer — from daily content audits to hourly data processing pipelines. This guide covers every scheduling option available in Claude Code and the Agent SDK, with practical patterns for macOS (launchd), Linux (cron), and cloud (GitHub Actions).

What "Scheduled Tasks" Means in Claude Code Context

There are three distinct scheduling patterns:

1. Claude Code CLI scheduled sessions — use /schedule to queue a Claude Code session to run at a specific time; Claude picks up where you left off
2. Agent SDK CronCreate tool — inside a Claude Code session, use the CronCreate tool to schedule recurring autonomous actions
3. External scheduling + Claude Code CLI — use cron/launchd/GitHub Actions to launch claude -p "..." on a schedule

Each pattern suits different use cases. This guide covers all three.

Pattern 1: Claude Code CLI /schedule

The /schedule command schedules a follow-up Claude Code task to run later in the same project context.

Basic Usage

Inside a Claude Code session:

/schedule in 2 hours: run bun run typecheck and report any errors

/schedule tomorrow at 9am: check if the Vercel deployment is healthy and summarize the last 24h of logs

/schedule every weekday at 8am: pull latest git changes, check for dependency updates, summarize in DAILY_SUMMARY.md

What Gets Scheduled

When you use /schedule, Claude Code:

1. Records the task and time
2. Launches a new session at the scheduled time (requires Claude Code to be running or a background daemon)
3. Executes the task with full project context from CLAUDE.md
4. Writes results to a file or sends a desktop notification

Prerequisites

For /schedule to fire reliably:

• Mac: Claude Code background service must be enabled (claude service start)
• The project directory must be accessible at scheduled time
• For server-side scheduling, use Pattern 3 instead

Pattern 2: Agent SDK CronCreate Tool

Inside any Claude Code session, the CronCreate tool schedules recurring autonomous tasks that persist across sessions.

Creating a Recurring Task

Use CronCreate to schedule a daily health check:
- Name: "daily-health-check"
- Schedule: every day at 6am
- Task: check site uptime, count new articles in content/, verify build passes
- Output: append to logs/daily-health.log

Claude Code will call CronCreate with the appropriate parameters. The scheduled task runs as an autonomous agent — no human in the loop.

Listing and Managing Scheduled Tasks

# See all scheduled tasks
Use CronList to show all active scheduled tasks

# Update a task
Use CronCreate with the same name to overwrite the existing schedule

# Remove a task
Use CronDelete to remove "daily-health-check"

Real Example: Daily Content Audit

I want to schedule a daily content quality check for claudeguide.io.
Use CronCreate to set this up:
- Name: "content-daily-audit"
- Schedule: every day at 7am UTC
- Task:
  1. Count articles in claudeguide-io/content/
  2. Find any article missing an FAQ section
  3. Check last commit was within 48 hours (content velocity)
  4. Write summary to logs/audit-YYYY-MM-DD.md

Pattern 3: External Scheduling + Claude Code CLI

The most reliable approach for production use: external schedulers call the Claude Code CLI directly.

macOS: launchd

Create a plist file at ~/Library/LaunchAgents/com.myapp.claude-task.plist:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>Label</key>
  <string>com.myapp.claude-daily-audit</string>

  <key>ProgramArguments</key>
  <array>
    <string>/usr/local/bin/claude</string>
    <string>--print</string>
    <string>--project</string>
    <string>/Users/me/my-project</string>
    <string>Run the daily content audit: count articles, check for missing FAQs, verify build passes. Write results to logs/audit.md.</string>
  </array>

  <key>StartCalendarInterval</key>
  <dict>
    <key>Hour</key>
    <integer>7</integer>
    <key>Minute</key>
    <integer>0</integer>
  </dict>

  <key>StandardOutPath</key>
  <string>/tmp/claude-audit.log</string>

  <key>StandardErrorPath</key>
  <string>/tmp/claude-audit-error.log</string>
</dict>
</plist>

Load it:

launchctl load ~/Library/LaunchAgents/com.myapp.claude-daily-audit.plist

# Verify it's loaded
launchctl list | grep com.myapp

# Run immediately to test
launchctl start com.myapp.claude-daily-audit

# Unload when done
launchctl unload ~/Library/LaunchAgents/com.myapp.claude-daily-audit.plist

Linux: cron

# Edit crontab
crontab -e

# Run Claude Code task daily at 7am UTC
0 7 * * * /usr/local/bin/claude --print --project /home/me/my-project "Run daily audit: check content count, build status, write to logs/audit.md" >> /tmp/claude-cron.log 2>&1

# Run every Monday at 9am
0 9 * * 1 /usr/local/bin/claude --print --project /home/me/my-project "Weekly summary: git log --since='7 days ago', deployment status, top 5 pages by traffic" >> /tmp/claude-weekly.log 2>&1

GitHub Actions: Cloud Scheduling

# .github/workflows/daily-audit.yml
name: Daily Claude Code Audit

on:
  schedule:
    - cron: '0 7 * * *'   # Daily at 7am UTC
  workflow_dispatch:        # Allow manual trigger

jobs:
  audit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install Claude Code
        run: npm install -g @anthropic-ai/claude-code

      - name: Run audit
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          claude --print "
            Audit this repository:
            1. Count markdown files in content/
            2. Check if bun run build succeeds
            3. Find any TODO comments in source files
            4. Write a summary to AUDIT_REPORT.md
          "

      - name: Commit audit report
        run: |
          git config user.name "Claude Code Bot"
          git config user.email "bot@example.com"
          git add AUDIT_REPORT.md
          git commit -m "chore: daily audit report $(date +%Y-%m-%d)" || true
          git push

Practical Automation Recipes

Recipe 1: Weekly Content Velocity Report

# cron: every Monday at 9am
claude --print --project /path/to/site "
  Generate a weekly content report:
  - Count articles added this week (git log --since='7 days ago' --name-only content/)
  - List any articles missing FAQ sections
  - Check average article length vs last week
  - Write to reports/weekly-$(date +%Y-%W).md
"

Recipe 2: Dependency Update Monitor

# cron: every Sunday at 8am
claude --print --project /path/to/app "
  Check for outdated dependencies:
  1. Run: npm outdated --json
  2. Identify packages with security patches available
  3. For minor/patch updates: apply them and run tests
  4. For major updates: list them in DEPENDENCY_UPDATES.md with breaking change notes
  Do NOT push to git — just stage the changes and write the report.
"

Recipe 3: Site Health Monitor

# cron: every hour
claude --print --project /path/to/site "
  Quick health check:
  1. Verify last Vercel deployment status (check vercel.json or deployment log)
  2. Count 404 errors in logs/access.log from the last hour
  3. If error count > 10: append alert to logs/alerts.log
  4. Otherwise: append OK status to logs/health.log
"

Recipe 4: Daily Standup Generator

# cron: every weekday at 8:45am
claude --print --project /path/to/project "
  Generate my daily standup from git history:
  1. git log --author='$(git config user.name)' --since='yesterday' --oneline
  2. Group commits by feature/type
  3. Write a 3-bullet standup to standup/$(date +%Y-%m-%d).md:
     - Yesterday: [what was completed]
     - Today: [inferred next steps based on open TODOs]
     - Blockers: [any TODO or FIXME comments added recently]
"

Key CLI Flags for Automation

When running Claude Code non-interactively:

Cost-Optimized Scheduling

For frequent automated tasks, use Haiku instead of Sonnet:

# Use Haiku for simple monitoring tasks (10x cheaper)
claude --print --model claude-haiku-4-5 --project /path "Check build status and write one-line result to status.txt"

# Use Sonnet for complex analysis (default)
claude --print --project /path "Analyze last week's git history and write a detailed retrospective"

Safety Rules for Automated Tasks

Scheduled Claude Code tasks run autonomously — wrong prompts cause real damage.

Always include scope limits:

# Dangerous — no scope limit
claude --print "Clean up the project"

# Safe — explicit boundaries
claude --print "
  Clean up ONLY the logs/ directory:
  - Delete .log files older than 30 days
  - Keep the 10 most recent files
  - Do NOT touch any other directories
  - List what was deleted in logs/cleanup.log
"

Use --max-turns for bounded tasks:

# Limit to 5 agentic steps maximum
claude --print --max-turns 5 "Run the test suite and summarize results"

Test manually before scheduling:

# Always run once manually first
claude --print --project /path/to/project "YOUR SCHEDULED TASK HERE"
# Verify the output is what you expected
# Then add to cron/launchd

Frequently Asked Questions

What is Claude Code scheduled tasks? Scheduled tasks in Claude Code are automated, timer-based executions of Claude Code sessions. You define a prompt and a schedule (via /schedule, CronCreate, cron, or launchd), and Claude Code runs autonomously at the specified time without human intervention.

Does Claude Code support cron-style scheduling natively? Yes. The Agent SDK includes CronCreate, CronList, and CronDelete tools for managing recurring scheduled tasks from within a Claude Code session. For system-level scheduling, you use the claude --print CLI flag with external schedulers like cron or launchd.

How much does running scheduled Claude Code tasks cost? It depends on the model and task complexity. A simple monitoring task with Haiku (1,000 input tokens, 200 output tokens) costs about $0.001 per run — less than $0.03/month if run hourly. Complex analysis tasks with Sonnet cost roughly 3-10x more.

Can scheduled tasks push to GitHub or deploy to Vercel? Yes, if the task prompt instructs it and the necessary credentials are available in the environment. Use with caution: always test manually first and include explicit scope constraints.

How do I stop a runaway scheduled task? Use --max-turns <n> to cap execution steps. For cron/launchd tasks, you can kill the process directly or remove the schedule entry. For Agent SDK tasks, use CronDelete or TaskStop.

What's the difference between /schedule and CronCreate? /schedule is a user-facing slash command for one-time or recurring tasks tied to the Claude Code UI. CronCreate is an Agent SDK tool that Claude itself can call to programmatically create scheduled tasks — useful when you want Claude to set up its own recurring workflows.

Related Guides

• Claude Code Complete Guide — Full Claude Code feature reference
• Claude Agent SDK: Build Automation Agents — Multi-step agent workflows
• CLAUDE.md Patterns That Save Time — Project configuration best practices

Go Deeper

Agent SDK Cookbook — $49 — 40 production-ready automation patterns including scheduled task templates, background processing pipelines, and multi-agent orchestration. Python + TypeScript code included.

→ Get the Agent SDK Cookbook — $49

30-day money-back guarantee. Instant download.