Cron Scheduler

PocketPaw includes a built-in task scheduler for recurring reminders and scheduled actions.

Features

• Recurring tasks — Schedule tasks with cron-like expressions
• Persistence — Recurring tasks survive restarts
• Re-scheduling — Tasks automatically re-schedule after execution
• Management — Add and delete recurring tasks via tools

How It Works

The scheduler is built on APScheduler and manages two types of tasks:

One-time Reminders

User: Remind me to check the build in 30 minutes
Agent: Set a reminder for 2:30 PM — "Check the build"

Recurring Tasks

User: Every Monday at 9 AM, summarize my calendar for the week
Agent: Created recurring task: "Weekly calendar summary" — Every Monday at 9:00 AM

API

The scheduler provides two main functions:

add_recurring

from pocketclaw.scheduler import scheduler

scheduler.add_recurring(
    task_id="weekly-summary",
    cron_expression="0 9 * * 1",  # Every Monday at 9 AM
    callback=async_function,
    kwargs={"session_id": "..."},
)

delete_recurring

scheduler.delete_recurring("weekly-summary")

Persistence

Recurring tasks are persisted to the config and re-loaded on startup. One-time reminders are stored in memory and lost on restart.

Cron Expression Format

Standard cron format: minute hour day_of_month month day_of_week