Scheduled Task Creation

Creating Claude Desktop Scheduled Tasks

Desktop scheduled tasks have TWO required components — both must exist or the task won't appear in the UI and won't fire.

Component 1: SKILL.md file

Location: ~/.claude/scheduled-tasks/{task-id}/SKILL.md

Format:

---
name: task-id
description: Short description of what it does and when it fires
---

[Prompt body — the exact instructions sent to Claude when the task fires]

Rules:

• YAML frontmatter has only name and description — nothing else
• The body is the prompt Claude receives at runtime
• The directory name must match the id in the registry entry

Component 2: Registry entry in scheduled-tasks.json

Location: ~/Library/Application Support/Claude/claude-code-sessions/*/scheduled-tasks.json

Find the file first:

find ~/Library/Application\ Support/Claude/claude-code-sessions -name "scheduled-tasks.json" 2>/dev/null

Registry entry schema:

{
  "id": "task-name-kebab-case",
  "cronExpression": "3 8 * * *",
  "enabled": true,
  "filePath": "/Users/YOU/.claude/scheduled-tasks/task-name/SKILL.md",
  "createdAt": 1775643180398,
  "cwd": "/Users/YOU",
  "useWorktree": false,
  "permissionMode": "acceptEdits",
  "notifySessionId": "optional-session-id"
}

Step-by-Step: Creating a New Scheduled Task

Step 1 — Write the SKILL.md

mkdir -p ~/.claude/scheduled-tasks/my-task-name

Create ~/.claude/scheduled-tasks/my-task-name/SKILL.md:

---
name: my-task-name
description: What this task does and when it fires (e.g. Daily market check, Mon-Fri 8am)
---

Your prompt here. Write the full instructions Claude will receive when this task fires.
Be specific — Claude has no other context at runtime.

Step 2 — Find the registry file

find ~/Library/Application\ Support/Claude/claude-code-sessions -name "scheduled-tasks.json" 2>/dev/null

This returns a path like: /Users/YOU/Library/Application Support/Claude/claude-code-sessions/abc123/scheduled-tasks.json

Step 3 — Add the entry to the registry

Read the current registry:

cat "/Users/YOU/Library/Application Support/Claude/claude-code-sessions/abc123/scheduled-tasks.json"

The file contains a JSON array. Add your new entry to the array. Use the current Unix timestamp in milliseconds for createdAt:

date +%s000

New entry to add:

{
  "id": "my-task-name",
  "cronExpression": "3 8 * * 1-5",
  "enabled": true,
  "filePath": "/Users/YOU/.claude/scheduled-tasks/my-task-name/SKILL.md",
  "createdAt": 1775643180398,
  "cwd": "/Users/YOU",
  "useWorktree": false,
  "permissionMode": "acceptEdits"
}

Write the updated array back to the file.

Step 4 — Verify in the Desktop app

Open Claude Desktop → Scheduled Tasks. The new task should appear. If it doesn't:

• Check that both the SKILL.md file and registry entry exist
• Verify the id in the JSON matches the directory name exactly
• Verify filePath is an absolute path to the SKILL.md

Key Rules and Gotchas

Cron format — standard 5-field: minute hour day-of-month month day-of-week

• 3 8 * * 1-5 → 8:03am Monday–Friday
• 3 15 * * 1-5 → 3:03pm Monday–Friday
• 3 9 1 * * → 9:03am on the 1st of each month
• */30 * * * * → every 30 minutes

Use :03 offset — schedule at :03 past the hour (e.g. 3 8 * *) instead of :00 to stagger API traffic.

Minimum interval — 1 minute for Desktop tasks.

permissionMode — use "acceptEdits" for most automated tasks (auto-approves file edits, still prompts for riskier actions). ⚠️ "bypassPermissions" runs with NO prompts at all — only opt into it for a task you fully trust, since a scheduled task running unattended with bypassed permissions can take any action without review.

useWorktree — set true if the task should run in an isolated git worktree. Usually false.

notifySessionId — optional; omit if not needed for session notifications.

Tasks only run when:

• The Claude Desktop app is open
• The computer is awake

Catch-up behavior — if the app was closed when a task was scheduled to fire, Desktop does one catch-up run when it reopens (looks back up to 7 days, runs once per missed task).

NEVER do this

Do NOT use the Cowork MCP create_scheduled_task tool — it writes to a separate, disconnected registry that the Desktop app does not read. Tasks created that way will not appear in the Desktop UI and will not fire.

Editing an Existing Task

• Change the prompt: edit ~/.claude/scheduled-tasks/{task-id}/SKILL.md — next run uses the updated instructions automatically.
• Change the schedule: update cronExpression in the registry JSON.
• Disable a task: set "enabled": false in the registry JSON.

Example: Full Working Task

SKILL.md at ~/.claude/scheduled-tasks/morning-briefing/SKILL.md:

---
name: morning-briefing
description: Daily morning briefing — checks news and portfolio, Mon-Fri 8am
---

Good morning. Please:
1. Check the latest financial news relevant to the portfolio
2. Summarize overnight market moves
3. Flag any urgent items that need attention today
Send a Telegram message with your briefing.

Registry entry in scheduled-tasks.json:

{
  "id": "morning-briefing",
  "cronExpression": "3 8 * * 1-5",
  "enabled": true,
  "filePath": "/Users/YOU/.claude/scheduled-tasks/morning-briefing/SKILL.md",
  "createdAt": 1775643180398,
  "cwd": "/Users/YOU",
  "useWorktree": false,
  "permissionMode": "acceptEdits"
}