Cron & Job System
Relevant source files
The following files were used as context for generating this wiki page:
The Cron & Job System in Clawdbot is a robust scheduling engine managed by the Gateway. It enables the execution of automated tasks, ranging from simple system events to complex agent-driven workflows. The system supports multiple schedule types, including one-shot execution, fixed intervals, and standard Unix cron expressions.
The core purpose of the system is to provide persistent, reliable task scheduling that can wake the agent even when it is not actively processing a user session. Jobs are categorized by their session target—either "main" for direct system event injection or "isolated" for background agent runs that can optionally deliver results to external channels like Telegram, Discord, or WhatsApp.
Sources: src/cron/service.js, ui/src/ui/views/cron.ts:77-105, apps/macos/Sources/Clawdbot/CronJobEditor.swift:13-22
System Architecture
The architecture is built around a centralized CronService running within the Gateway. This service manages a persistent store of jobs, handles timer logic, and interfaces with the agent execution environment.
Components and Data Flow
The system interacts through three primary interfaces:
- Gateway RPC API: Provides methods like
cron.add,cron.update, andcron.runfor programmatic control. - CLI: A shared library facilitates job management and status reporting via the terminal.
- UI (Web & macOS): Graphical interfaces for creating and monitoring jobs, utilizing the RPC API.
This diagram shows the flow from user interfaces through the Gateway RPC to the Cron Service, which manages persistence, execution, and logging.
Sources: src/gateway/server-methods/cron.ts:1-135, src/cli/cron-cli/shared.ts:114-175, ui/src/ui/views/cron.ts:1-200
Job Configuration and Payload
A job is defined by its metadata, schedule, and execution payload. The system enforces strict validation based on the sessionTarget.
Session Targets and Payloads
| Target | Description | Allowed Payloads |
|---|---|---|
| Main | Injects events into the active primary session. | systemEvent (text-based) |
| Isolated | Runs a dedicated background agent session. | agentTurn (message + parameters) |
Sources: apps/macos/Sources/Clawdbot/CronJobEditor+Helpers.swift:125-141, src/cron/service.js
Payload Structures
systemEvent
Used for triggering general system behaviors or reminders in the main chat.
- text: The content of the system event.
agentTurn
Complex payload for isolated runs involving agent logic.
- message: The prompt/instruction for the agent.
- thinking: Optional thinking level (e.g., "low").
- deliver: Boolean indicating if results should be sent to an external channel.
- channel: Target channel (e.g., "telegram", "discord", "whatsapp", or "last").
- to: Specific recipient ID or phone number.
- timeoutSeconds: Execution limit for the agent.
Sources: apps/macos/Sources/Clawdbot/CronJobEditor+Helpers.swift:156-173, ui/src/ui/views/cron.ts:145-185
Scheduling Engine
The system supports three distinct scheduling "kinds," allowing for versatile automation patterns.
| Kind | Parameter | Description |
|---|---|---|
| At | atMs | A specific timestamp for a one-shot execution. |
| Every | everyMs | A repeating interval duration (e.g., 10m, 1h, 1d). |
| Cron | expr, tz | A standard 5-field Unix cron expression with optional timezone support. |
Wake Modes
The wakeMode determines how the Gateway initiates the job:
- next-heartbeat: Waits for the next scheduled heartbeat to process the job.
- now: Attempts immediate execution upon reaching the scheduled time.
Sources: src/cli/cron-cli/shared.ts:89-93, apps/macos/Sources/Clawdbot/CronJobEditor+Helpers.swift:97-123
Execution Flow
When a job reaches its scheduled time, the CronService manages the execution lifecycle, including locking to prevent concurrent runs of the same job.
The sequence diagram illustrates the job execution cycle, from timer firing to result logging and state update.
Sources: src/gateway/server.cron.e2e.test.ts:162-185, src/cron/service.js
RPC API Endpoints
The Gateway exposes several endpoints for managing the Cron system.
| Endpoint | Parameters | Description |
|---|---|---|
cron.list | includeDisabled | Returns a list of all configured jobs. |
cron.add | CronJobCreate | Registers a new job with the service. |
cron.update | id, patch | Updates specific fields of an existing job. |
cron.run | id, mode | Manually triggers a job (mode: "force" or "due"). |
cron.runs | id, limit | Retrieves history entries from the .jsonl run log. |
cron.remove | id | Deletes a job and stops its timers. |
cron.status | (none) | Returns scheduler status (enabled, job count, next wake). |
Sources: src/gateway/server-methods/cron.ts:24-134
UI and Management
The system provides detailed visibility into job states and historical performance.
Job State Monitoring
The CronJob object tracks:
- lastStatus: Result of the previous run (e.g., "ok", "error", "skipped").
- lastRunAtMs: Timestamp of the last successful start.
- nextRunAtMs: Calculation of the next scheduled execution time.
- runningAtMs: Present if the job is currently executing, serving as a lock.
Sources: src/cli/cron-cli/shared.ts:100-104, ui/src/ui/views/cron.ts:285-300
Run History
Execution details are persisted in job-specific JSONL files within the cron/runs/ directory. Each entry includes the status, summary (e.g., agent output), duration, and any error messages encountered.
Sources: src/gateway/server.cron.e2e.test.ts:162-175, ui/src/ui/views/cron.ts:335-348
Summary
The Cron & Job System provides Clawdbot with reliable background automation capabilities. By separating jobs into "main" session events and "isolated" agent turns, it allows users to schedule routine tasks without cluttering primary conversation histories, while the integration of run logs ensures auditability and troubleshooting capabilities for automated workflows.