/scheduling-tasks

name: scheduling-tasks
description: Schedules reminders and recurring tasks via the letta cron CLI. Use when the user asks to be reminded of something, wants periodic work or check-ins, or needs to list, inspect, replace, or cancel scheduled 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.

When to Use This Skill

• User asks to be reminded of something ("remind me to X at Y")
• User wants a recurring check-in ("every morning ask me about X")
• User wants a one-shot delayed message ("in 30 minutes, check on X")
• User wants to see or cancel existing scheduled tasks

Where Schedules Run — Omit the Flags

**Default guidance: omit `--runner` and `--computer`.** The CLI places the schedule so the work keeps running on the computer where it was created. Don't move scheduled work to a different computer than the active conversation without a reason: two computers working the same conversation can conflict.

Pass a flag only when you have a requirement the default can't infer:

• **`--runner cloud`** — the schedule must fire no matter which computers are online; execute in the agent's cloud sandbox.
• **`--computer <deviceId>`** — the work needs a specific connected computer (its filesystem, services, or credentials). Get the deviceId from `letta environments list`. If that computer is offline at fire time, execution falls back to the cloud sandbox.
• **`--runner local`** — the work must only ever run on the current computer, even if that means missing fires while no session is running here.

The CLI reports its placement in the command output. If it warns that the schedule is local (this happens when the cloud scheduler cannot reach the current computer), the schedule only fires while a Letta session is running here — read the warning and decide whether that's acceptable.

Fast Follow-ups vs Recurring Jobs

Two patterns cover most schedules:

• **Fast follow-ups** ("check on the PR in 5m"): the default is right — same computer as the active conversation. If the session dies before it fires, the follow-up usually died with the task anyway.
• **Recurring jobs** ("every Monday 11am, start the lunch order"): prefer durability. If the CLI warned that a recurring schedule is local, that's usually wrong for the user's intent — recreate it with `--runner cloud`, or `--computer` if the job needs a specific always-on computer. Also consider whether the job should post into a dedicated conversation rather than this one (continuity in one thread vs a fresh context per 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:**

| Flag | Description | |------|-------------| | `--name <text>` | Short identifier for the task (e.g. "dog-walk-reminder") | | `--description <text>` | Human-readable description of what the task does | | `--prompt <text>` | The message that will be sent to the agent when the task fires |

**Schedule (pick one):**

| Flag | Type | Example | |------|------|---------| | `--every <interval>` | Recurring (cron shorthand) | `5m`, `2h`, `1d` | | `--at <time>` | One-shot | `"3:00pm"`, `"in 45m"` | | `--cron <expr>` | Raw cron (recurring) | `"0 9 * * 1-5"` |

**Optional flags:**

| Flag | Description | |------|-------------| | `--agent <id>` | Agent ID (defaults to `LETTA_AGENT_ID` from the current shell/session) | | `--conversation <id>` | Conversation ID (defaults to `LETTA_CONVERSATION_ID` from the current shell/session, otherwise `"default"`) | | `--runner <runner>` | `cloud` or `local` — normally omit; see "Where Schedules Run" above | | `--computer <id>` | Execute on a specific connected computer — normally omit | | `--once` | Mark `--at` as one-shot (already the default for `--at`) |

Listing Tasks

letta cron list

Optional filters: `--agent <id>`, `--conversation <id>`, `--runner local|cloud`

Getting a Single Task

`get` accepts an ID or name:

letta cron get <id-or-name> [--runner local|cloud] [--agent <id>]

Reading Run History

letta cron runs --id <task-id> [--limit <n>] [--runner local|cloud] [--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` will otherwise fall back to `LETTA_AGENT_ID` and `LETTA_CONVERSATION_ID` from the current shell/session. Those values may be correct for the current chat, but they can also be inherited from surrounding tooling, another conversation, or an older shell.

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 "$AGENT_ID" \
  --conversation "$CONVERSATION_ID"

Then verify the binding explicitly:

letta cron list --agent "$AGENT_ID" --conversation "$CONVERSATION_ID"

Deleting or Replacing Tasks

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

# Delete a specific task
letta cron delete <id-or-name> [--runner local|cloud] [--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 — Convert Before Writing `--cron`

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