Cron and Task Scheduling

Claude Code has a built-in cron-style scheduler that lets the model queue prompts for future execution — either once at a specific time or on a recurring schedule. The entire system is built around a single JSON file (.claude/scheduled_tasks.json) and a polling loop that ticks every second inside the running REPL.

Three user-facing tools drive the system: CronCreate, CronDelete, and CronList. Behind them sits a non-React scheduler core (cronScheduler.ts) shared by the interactive REPL and the headless SDK daemon, connected to the REPL via the useScheduledTasks React hook.

Every scheduled task is represented by a CronTask object. The disk shape is intentionally minimal — runtime-only fields are stripped before writing.

// utils/cronTasks.ts
export type CronTask = {
  id:        string         // 8-hex UUID slice — enough for MAX_JOBS=50
  cron:      string         // 5-field cron in LOCAL time
  prompt:    string         // what to enqueue when the task fires
  createdAt: number         // epoch ms — anchor for missed-task detection

  lastFiredAt?: number     // written back after each recurring fire
  recurring?:   boolean    // true = reschedule; false/undefined = delete on fire
  permanent?:   boolean    // exempt from recurringMaxAgeMs auto-expiry

  // Runtime-only — never written to disk:
  durable?:  boolean       // false = session-scoped (in-memory only)
  agentId?:  string        // routes fires to a specific in-process teammate
}

Two flavors of task exist depending on recurring:

The scheduler is created once per REPL session by createCronScheduler() and managed through a simple { start, stop, getNextFireTime } interface. The lifecycle has a deliberate lazy-enable design to avoid loading chokidar and the file system machinery until tasks actually exist.

The check() inner loop

Every second, check() iterates all loaded file tasks (if lock-owner) and all session tasks from bootstrap state. For each task it:

// cronScheduler.ts — simplified check() inner loop
function process(t: CronTask, isSession: boolean) {
  let next = nextFireAt.get(t.id)
  if (next === undefined) {
    // First sight: anchor from lastFiredAt (if previously fired) or createdAt.
    // Anchoring from lastFiredAt prevents "stale spawn" re-firing every cycle.
    next = t.recurring
      ? jitteredNextCronRunMs(t.cron, t.lastFiredAt ?? t.createdAt, t.id, jitterCfg)
      : oneShotJitteredNextCronRunMs(t.cron, t.createdAt, t.id, jitterCfg)
    nextFireAt.set(t.id, next ?? Infinity)
  }
  if (now < next) return  // not yet

  // Fire!
  onFireTask ? onFireTask(t) : onFire(t.prompt)

  if (t.recurring && !aged) {
    // Reschedule from now — not from next — to avoid rapid catch-up after blocking.
    nextFireAt.set(t.id, jitteredNextCronRunMs(t.cron, now, t.id, jitterCfg))
    if (!isSession) firedFileRecurring.push(t.id) // batch lastFiredAt write
  } else {
    // One-shot or aged recurring: remove from store / file.
    isSession ? removeSessionCronTasks([t.id]) : removeCronTasks([t.id])
  }
}

A user can run multiple Claude sessions in the same project directory simultaneously. Without coordination, both sessions would fire the same on-disk task — duplicating work. Claude Code solves this with a per-project scheduler lock.

// cronScheduler.ts — lock acquisition in enable()
isOwner = await tryAcquireSchedulerLock(lockOpts).catch(() => false)

if (!isOwner) {
  // Non-owner: probe for lock takeover every 5s.
  // Coarse because takeover only matters when the owning session crashes.
  lockProbeTimer = setInterval(() => {
    tryAcquireSchedulerLock(lockOpts).then(owned => {
      if (owned) { isOwner = true; clearInterval(lockProbeTimer) }
    })
  }, 5000) // LOCK_PROBE_INTERVAL_MS
  lockProbeTimer.unref?.()
}

The lock is liveness-probed by PID. If the owning process dies without calling stop(), a non-owning session will detect the stale lock on its next 5-second probe and take over.

The stop() method always releases the lock:

// cronScheduler.ts
stop() {
  stopped = true
  clearInterval(checkTimer)
  clearInterval(lockProbeTimer)
  void watcher?.close()
  if (isOwner) {
    isOwner = false
    void releaseSchedulerLock(lockOpts)
  }
}

When millions of users schedule tasks at the same time ("every hour", "at 9am"), they all generate inference requests simultaneously — a thundering herd. Claude Code adds deterministic per-task jitter to spread these spikes across the fleet.

The jitter amount is derived from the task ID (an 8-hex-char UUID slice):

// cronTasks.ts — stable per-task fraction in [0, 1)
function jitterFrac(taskId: string): number {
  const frac = parseInt(taskId.slice(0, 8), 16) / 0x1_0000_0000
  return Number.isFinite(frac) ? frac : 0
}

This fraction is stable across restarts (same taskId = same jitter), uniformly distributed across the fleet, and requires no coordination. Two strategies apply depending on task type:

Recurring tasks — forward jitter

// Forward jitter: fires up to recurringFrac * interval late (cap: recurringCapMs)
export function jitteredNextCronRunMs(cron, fromMs, taskId, cfg): number | null {
  const t1 = nextCronRunMs(cron, fromMs)   // next fire
  const t2 = nextCronRunMs(cron, t1)        // one-after (for interval))
  if (t2 === null) return t1               // pinned date — no herd risk
  const jitter = Math.min(
    jitterFrac(taskId) * cfg.recurringFrac * (t2 - t1),
    cfg.recurringCapMs,
  )
  return t1 + jitter
  // e.g. hourly at cfg defaults (frac=0.1, cap=15min):
  // spread = jitterFrac(id) * 0.1 * 3600000ms = up to 360s = 6 min
}

One-shot tasks — backward jitter

// Backward jitter: fires up to oneShotMaxMs early, only on :00/:30 minutes
export function oneShotJitteredNextCronRunMs(cron, fromMs, taskId, cfg): number | null {
  const t1 = nextCronRunMs(cron, fromMs)
  // Only jitter "round" minutes — humans pick :00 and :30, bots don't.
  if (new Date(t1).getMinutes() % cfg.oneShotMinuteMod !== 0) return t1
  const lead = cfg.oneShotFloorMs + jitterFrac(taskId) * (cfg.oneShotMaxMs - cfg.oneShotFloorMs)
  return Math.max(t1 - lead, fromMs)  // never fire before creation
}

Default jitter config values

CronCreate

The model calls CronCreate with a 5-field cron string, a prompt, and optional recurring and durable flags.

// CronCreateTool.ts — input schema
z.strictObject({
  cron:      z.string(),     // "*/5 * * * *" — 5-field local time
  prompt:    z.string(),     // what to run at fire time
  recurring: z.boolean().optional(),  // default: true
  durable:   z.boolean().optional(),  // default: false (session-only)
})

Validation is strict: the cron expression is parsed and checked against the next 366 days. A hard cap of 50 jobs prevents runaway scheduling. Teammate agents cannot create durable crons (their agentId would orphan on restart). After a successful create, setScheduledTasksEnabled(true) flips the bootstrap flag to kick the enablePoll loop into action immediately.

CronDelete

Takes a job ID, validates it exists (and belongs to the calling teammate if in teammate context), then calls removeCronTasks([id]). Teammate isolation is enforced: a teammate can only delete crons with a matching agentId.

CronList

Returns all tasks merged from disk and the session store. Teammates see only their own crons; the team lead sees everything. The tool is marked isReadOnly() and isConcurrencySafe() — it never writes and can run alongside other tool calls.

// CronListTool.ts — teammate scoping
const ctx = getTeammateContext()
const tasks = ctx
  ? allTasks.filter(t => t.agentId === ctx.agentId)  // teammate sees own crons only
  : allTasks                                              // lead sees all

The useScheduledTasks hook is the bridge between the React REPL and the non-React scheduler core. It mounts the scheduler exactly once and tears it down on unmount.

// hooks/useScheduledTasks.ts
export function useScheduledTasks({ isLoading, assistantMode, setMessages }: Props) {
  const isLoadingRef = useRef(isLoading)
  isLoadingRef.current = isLoading  // latest-value ref — no stale closure

  useEffect(() => {
    if (!isKairosCronEnabled()) return  // runtime gate

    const scheduler = createCronScheduler({
      onFire: prompt => enqueuePendingNotification({
        value: prompt, mode: 'prompt',
        priority: 'later',   // drains between turns — never interrupts
        isMeta: true,        // hidden from transcript UI
        workload: WORKLOAD_CRON, // lower QoS — no human waiting
      }),
      onFireTask: task => {
        if (task.agentId) {
          // Route to teammate agent instead of main REPL queue
          injectUserMessageToTeammate(teammate.id, task.prompt, setAppState)
          return
        }
        // Show "Running scheduled task (Mar 31 9:03am)" in transcript
        setMessages(prev => [...prev, createScheduledTaskFireMessage(...)])
        enqueueForLead(task.prompt)
      },
      isLoading: () => isLoadingRef.current,
      getJitterConfig: getCronJitterConfig,
      isKilled: () => !isKairosCronEnabled(),  // polled every tick — live killswitch
    })
    scheduler.start()
    return () => scheduler.stop()
  }, [assistantMode])
}

Fired prompts are enqueued at 'later' priority via enqueuePendingNotification. The REPL's useCommandQueue drains this queue between turns — so a cron task never interrupts an active query. The WORKLOAD_CRON attribution flows through to the API billing header, allowing lower Quality-of-Service for automated background requests vs interactive ones.

If Claude was not running when a task was scheduled to fire, it detects this on startup. findMissedTasks() computes each task's first fire time from createdAt and compares to Date.now():

// cronTasks.ts
export function findMissedTasks(tasks: CronTask[], nowMs: number): CronTask[] {
  return tasks.filter(t => {
    const next = nextCronRunMs(t.cron, t.createdAt)
    return next !== null && next < nowMs
  })
}

Missed one-shot tasks are surfaced to the user with a notification prompt built by buildMissedTaskNotification(). The notification:

• Includes the task's cron expression in human-readable form and creation timestamp.
• Wraps each prompt in a code fence to prevent accidental prompt injection (uses a fence one backtick longer than any backtick run inside the prompt).
• Explicitly instructs the model not to execute yet — first ask the user via AskUserQuestion.
• Deletes the tasks from disk before the model sees the notification.

Missed recurring tasks are intentionally NOT surfaced. The scheduler's check() handles them correctly by firing on the first tick and rescheduling forward from there. Surfacing them would produce a misleading "missed while Claude was not running" prompt for tasks that were merely overdue, not missed.

const longestRun = (t.prompt.match(/`+/g) ?? []).reduce(
  (max, run) => Math.max(max, run.length), 0
)
const fence = '`'.repeat(Math.max(3, longestRun + 1))

The scheduling system has multiple independently-operable gates: