Scheduling Tasks

Scheduling Tasks

This skill lets you create, list, and manage scheduled tasks using the letta cron CLI. Scheduled tasks send a prompt to the agent on a timer — useful for reminders, periodic check-ins, and deferred follow-ups.

For ordinary one-shot or recurring work in the current conversation, use Wake instead. Wake is self-bound and covers create, list, and cancel without routing choices.

When to Use This Skill

• The task should run in a fresh, default, or different conversation
• The task needs a specific connected computer
• You need run history, replacement, or broader schedule inspection
• Wake cannot see or manage the schedule you need

Where Schedules Run

Execution determines schedule ownership; there is no runner selection flag:

• In a managed Cloud sandbox, schedules are durable Cloud schedules and run in the agent's Cloud sandbox.
• On a user-managed computer or self-hosted runtime, schedules are local and fire only while a Letta session is running there.

From a managed Cloud sandbox, --computer <deviceId> can run the scheduled work on a specific connected computer. Get the device ID from letta computers list. If that computer is offline at fire time, execution falls back to the Cloud sandbox. Local execution cannot target another computer.

Creation and execution follow those rules, while management commands still show and cancel both local and Cloud inventory. This keeps schedules created by older CLI versions visible without changing where new schedules run.

CLI Usage

All commands go through letta cron via the Bash tool. Output is JSON.

Creating a Task

letta cron add --name <short-name> --description <text> --prompt <text> <schedule>

Required flags:

Schedule (pick one):

Optional flags:

Listing Tasks

letta cron list

Optional filters: --agent <id>, --conversation <id>

Getting a Single Task

get accepts an ID or name:

letta cron get <id-or-name> [--agent <id>]

Reading Run History

letta cron runs --id <task-id> [--limit <n>] [--agent <id>]

For local run history, --run-id <id> selects one run. Cloud history ignores that flag.

Binding a Task to the Right Conversation

If exact routing matters, pass both --agent and --conversation explicitly.

letta cron add falls back to LETTA_AGENT_ID for the agent. An omitted --conversation means "new", so every fire gets a fresh conversation. Pass --conversation self to capture the current LETTA_CONVERSATION_ID, --conversation default for the agent default, or a concrete conversation ID.

Safest pattern:

letta cron add \
  --name "email-check" \
  --description "Daily email summary in this conversation" \
  --prompt "Check the user's email and post a summary here." \
  --cron "0 10 * * *" \
  --agent "$LETTA_AGENT_ID" \
  --conversation self

Then verify the binding explicitly:

letta cron list --agent "$LETTA_AGENT_ID" --conversation self

Deleting or Replacing Tasks

delete accepts an ID or name; remove is an alias.

# Delete a specific task
letta cron delete <id-or-name> [--agent <id>]

# Delete all tasks for one agent
letta cron delete --all --agent "$AGENT_ID"

In-place editing is not available. To change a schedule, create and verify the replacement before deleting the old one.

Timezones

Cloud-schedule recurring expressions (both --cron and the expression --every compiles to) are interpreted in UTC. Users say times in their local timezone, so convert before writing the expression: a user in PDT asking for "9am daily" needs --cron "0 16 * * *" (9am PDT = 16:00 UTC; 17:00 during PST). State the conversion in your reply so the user can catch a wrong assumption. Local-runner recurring tasks use the computer's local timezone.

For a one-shot calendar request such as "tomorrow at 9am," resolve the date in the user's timezone and pass --at an RFC 3339 timestamp with an explicit offset. Infer a reasonable timezone from available context instead of asking a redundant follow-up. State the timezone you used in the confirmation (for example, "Scheduled for 9:00 AM PT") so the user can correct the assumption. A bare clock such as --at "9:00am" uses the current process timezone, which may be UTC in Cloud; use it only when that is the intended timezone. Relative values such as --at "in 45m" do not need a timezone.