Local Scheduling: Desktop Tasks, Cron, and One-Shot Reminders

The Three Scheduling Layers

Claude Code offers three distinct places to schedule recurring or one-off work, and the right choice depends on two questions: does the task need your machine, and does it need an open session?

Desktop scheduled tasks occupy the middle position: more persistent than /loop (they survive closing and reopening the app), but more local than cloud Routines (they need your machine on and have full access to your files and MCP servers).

Desktop Tasks: Local, Persistent, Familiar

A Desktop scheduled task starts a fresh Claude Code session automatically at the configured time, independent of any sessions you have open manually. Each run gets a new session — you can open it in the sidebar, review what Claude did, respond to permission prompts, or continue the conversation. Scheduled sessions show up under a Scheduled section in the sidebar.

The Desktop app checks the schedule every minute and fires tasks within a few minutes of the scheduled time. The offset is deterministic — the same task always starts at the same offset from the hour. This stagger prevents multiple tasks from all hitting the API at exactly :00.

Each task has its own permission mode, set when you create it. If a task runs in Ask mode and hits a tool it doesn't have permission for, the session stalls until you respond. The safest setup: click Run now after creating a task, approve every permission prompt that comes up, and select "always allow" for each tool. Future runs then auto-approve those same tools.

Creating a Desktop Task

In the Desktop app, click Routines in the sidebar, then New routine and choose Local. The form asks for:

• Name: becomes the task folder name in ~/.claude/scheduled-tasks/
• Instructions: what Claude should do each run — write this exactly as you'd type it in the prompt box
• Schedule: presets are Manual, Hourly, Daily, Weekdays, and Weekly; for custom intervals, describe them to Claude in any session
• Folder: the working directory for the task — required before saving

You can also create tasks conversationally. In any Desktop session, describe what you want: "set up a daily code review that runs every morning at 9am" or "remind me at 3pm tomorrow to check the deploy." Claude creates the task and confirms the schedule.

Each Desktop task's instructions are stored in ~/.claude/scheduled-tasks/<task-name>/SKILL.md. You can edit this file directly to update the prompt; changes take effect on the next run.

Missed Runs and Catch-Up

Desktop tasks don't silently skip missed runs. When the app starts or your computer wakes, it checks whether each task missed any runs in the last seven days. If it did, it starts exactly one catch-up run for the most recently missed time and discards anything older. A daily task that missed six days runs once on wake — not six times.

This matters for prompt design. A task scheduled for 9am might actually run at 11pm if your computer was asleep all day. If timing matters, add guards to the prompt: "Only process commits from today. If it's after 5pm, post a summary of what was missed and stop."

Session-Scoped Reminders and Cron

For one-shot reminders within a session, skip the Desktop task form and just describe the reminder to Claude in natural language:

remind me at 3pm to push the release branch

in 45 minutes, check whether the integration tests passed

Claude converts these to cron expressions, schedules a single-fire task, and confirms the exact time it will fire. One-shot tasks delete themselves after firing.

If you need a custom cron expression for a repeating task, you can ask Claude directly: "schedule the test suite to run every 15 minutes." Claude creates a CronCreate entry with the right expression. Standard five-field cron applies: minute hour day-of-month month day-of-week. All fields support wildcards (*), single values (5), steps (*/15), ranges (1-5), and comma-separated lists (1,15,30).

All times are interpreted in your local timezone. 0 9 * * * means 9am wherever you're running Claude Code, not UTC.

Set CLAUDE_CODE_DISABLE_CRON=1 to turn off the scheduler entirely, making the cron tools and /loop unavailable for that environment.

When Each Layer Fits

Choose /loop when the task only matters while you're in the session — checking a deployment you just kicked off, monitoring a build you're actively watching, polling a PR you're waiting on. When the session ends, the loop stops, and that's fine.

Choose Desktop tasks when the task needs to run at a predictable time, access your local files or MCP servers, and survive between sessions — but you accept that it won't run if your machine is off. Morning standup prep, daily dependency audits, end-of-day commit summaries all fit here.

Choose cloud Routines when the task must run even when your laptop is closed — nightly runs, PR review automation triggered by GitHub events, alert-driven workflows called by an API. The next lesson covers Routines in detail, but the rule of thumb is: if your machine needs to be on, use Desktop; if the task needs to run without you, use cloud.