Scheduling Tools

Claude Code includes a cron-based scheduling system that allows Claude to schedule recurring or one-shot prompts. The system consists of three tools: CronCreate, CronDelete, and CronList.

Overview

The scheduling system uses standard 5-field cron expressions interpreted in local time. Jobs can be:

• Recurring: Fire on every cron match until deleted or auto-expired
• One-shot: Fire once at the next match, then auto-delete
• In-memory: Die when the Claude session ends (default)
• Durable: Persist to .claude/scheduled_tasks.json and survive restarts

CronCreate

Creates a new scheduled task.

Parameters

Validation

• The cron expression must be parseable as a valid 5-field expression
• The expression must match at least one calendar date in the next year
• Maximum of 50 active jobs per session

Output

{
  id: string            // Unique job identifier
  humanSchedule: string // Human-readable description (e.g., "every 5 minutes")
  recurring: boolean    // Whether the job repeats
  durable?: boolean     // Whether the job persists to disk
}

CronDelete

Removes a scheduled task by its ID.

Parameters

Validation

• The job must exist in the current task list
• Teammates in a multi-agent setup can only delete their own cron jobs (ownership is checked via agentId)

Output

{
  id: string  // The ID of the deleted job
}

CronList

Lists all active scheduled tasks.

Parameters

This tool takes no input parameters.

Behavior

• In a multi-agent (team) context, teammates only see their own cron jobs
• The team lead (no teammate context) sees all jobs

Output

{
  jobs: Array<{
    id: string
    cron: string           // Raw cron expression
    humanSchedule: string  // Human-readable schedule description
    prompt: string         // The scheduled prompt
    recurring?: boolean    // Whether the job repeats
    durable?: boolean      // Whether the job persists to disk
  }>
}

Availability

The scheduling tools are gated behind two conditions:

1. Build-time: The AGENT_TRIGGERS feature flag must be enabled at compile time (dead code elimination)
2. Runtime: The tengu_kairos_cron GrowthBook gate must be true (checked with a 5-minute refresh, defaults to true)

The CLAUDE_CODE_DISABLE_CRON environment variable provides a local override that wins over the GrowthBook gate.

Durable Cron

Durable (disk-persistent) cron is gated separately. When the durable gate is off, durable: false is forced at the call site, leaving session-only cron unaffected.

Key Properties (All Cron Tools)

• Deferred: Yes (all three require ToolSearch)
• CronList is read-only and concurrency-safe
• CronCreate and CronDelete are not concurrency-safe
• maxResultSizeChars: 100,000

Key Source Files

• src/tools/ScheduleCronTool/CronCreateTool.ts: Job creation with validation
• src/tools/ScheduleCronTool/CronDeleteTool.ts: Job deletion with ownership checks
• src/tools/ScheduleCronTool/CronListTool.ts: Job listing with team scoping
• src/tools/ScheduleCronTool/prompt.ts: Feature gate checks and prompt generation
• src/utils/cronTasks.ts: Cron task storage, expiration, and management
• src/utils/cron.ts: Cron expression parsing and human-readable conversion